README

Framework-agnostic HTTP client for the T-Bank (Tinkoff) Acquiring API v2.

The package contains only the transport-facing layer: typed request objects, typed response DTOs, token signing/verification, response mapping, receipt DTOs, and a small TbankClient wrapper over noith/api-requester.

Requirements

Installation

composer require noith/tbank

Creating a Client

use Noith\TBank\TbankClient;

$tbank = new TbankClient(
    terminalKey: 'your-terminal',
    secretKey: 'your-secret',
    apiUrl: 'https://securepay.tinkoff.ru/v2',
    cashboxUrl: 'https://securepay.tinkoff.ru/cashbox',
);

SendClosingReceipt uses the cashbox API. If you call that endpoint, pass the cashbox URL explicitly when it differs from the default:

$tbank = new TbankClient(
    terminalKey: 'your-terminal',
    secretKey: 'your-secret',
    cashboxUrl: 'https://securepay.tinkoff.ru/cashbox',
);

Usage

use Noith\TBank\Requests\ConfirmRequest;
use Noith\TBank\Requests\GetQrRequest;
use Noith\TBank\Requests\InitRequest;

$init = $tbank->send(new InitRequest(
    orderId: 'order-1',
    amount: 150000,
    description: 'Order #1',
    notificationUrl: 'https://example.com/tbank/webhook',
    successUrl: 'https://example.com/paid',
    failUrl: 'https://example.com/failed',
));

$paymentUrl = $init->paymentUrl;

$qr = $tbank->send(new GetQrRequest($init->paymentId));

$confirmed = $tbank->send(new ConfirmRequest($init->paymentId));

Available requests:

Two-stage payments use TbankPayType (O one-stage / T two-stage) on InitRequest, then send() a ConfirmRequest or CancelRequest for the authorized amount.

Receipts

Use Noith\TBank\DTO\Receipt DTOs when an endpoint accepts a T-Bank Receipt payload: InitRequest, ConfirmRequest, CancelRequest, and SendClosingReceiptRequest. Pick the DTO variant that matches the fiscal data format configured for the terminal.

use Noith\TBank\DTO\Receipt\TbankReceiptFfd105;
use Noith\TBank\DTO\Receipt\TbankReceiptItemFfd105;
use Noith\TBank\Enums\Taxation;
use Noith\TBank\Enums\VatRate;
use Noith\TBank\Requests\InitRequest;

$receipt = new TbankReceiptFfd105(
    taxation: Taxation::OSN,
    email: 'buyer@example.com',
    items: [
        new TbankReceiptItemFfd105(
            name: 'Subscription',
            price: 150000,
            quantity: 1,
            amount: 150000,
            tax: VatRate::VAT22,
        ),
    ],
);

$request = new InitRequest(
    orderId: 'order-1',
    amount: 150000,
    receipt: $receipt,
);

For FFD 1.2, receipt items additionally require MeasurementUnit, PaymentMethod, and the FFD 1.2 PaymentObject enum:

use Noith\TBank\DTO\Receipt\TbankReceiptFfd12;
use Noith\TBank\DTO\Receipt\TbankReceiptItemFfd12;
use Noith\TBank\Enums\PaymentMethod;
use Noith\TBank\Enums\PaymentObjectFfd12;
use Noith\TBank\Enums\Taxation;
use Noith\TBank\Enums\VatRate;

$receipt = new TbankReceiptFfd12(
    taxation: Taxation::OSN,
    email: 'buyer@example.com',
    items: [
        new TbankReceiptItemFfd12(
            name: 'Subscription',
            price: 150000,
            quantity: 1,
            amount: 150000,
            tax: VatRate::VAT22,
            measurementUnit: 'шт',
            paymentMethod: PaymentMethod::FULL_PAYMENT,
            paymentObject: PaymentObjectFfd12::SERVICE,
        ),
    ],
);

Webhook Signature Verification

This package does not register routes or process webhook side effects. It only provides signature verification:

if (!$tbank->verify($payload)) {
    // Reject invalid notification.
}

After verification, map T-Bank statuses in your application or integration layer. Raw status values are available in TbankPaymentStatus.

Errors

T-Bank usually returns logical API errors as HTTP 200 responses with Success=false or a non-zero ErrorCode. TbankResponseMapper converts these responses into TbankApiException.

Testing

composer test