PHP code example of webmasterolegan / tbank-payments

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

webmasterolegan / tbank-payments example snippets

use TBank\Payments\Enum\EnvironmentEnum;
use TBank\Payments\TBankClient;
use TBank\Payments\DTO\Request\InitPaymentRequestDto;
use TBank\Payments\DTO\Shared\{ReceiptDto, ReceiptItemDto};
use TBank\Payments\Enum\Fiscal\{TaxationEnum, VatEnum};

$client = new TBankClient(
    terminalKey: 'YOUR_TERMINAL_KEY',
    password   : 'YOUR_PASSWORD',
    environment: EnvironmentEnum::Production,
);

use TBank\Payments\Enum\{LanguageEnum, PayTypeEnum};

$request = new InitPaymentRequestDto(
    amount     : 150000,
    orderId    : 'order-2024-001',
    description: 'Заказ #2024-001',
    payType    : PayTypeEnum::OneStep,
    language   : LanguageEnum::Ru,
    successUrl : 'https://myshop.ru/success',
    failUrl    : 'https://myshop.ru/fail',
    receipt    : new ReceiptDto(
        taxation: TaxationEnum::UsnIncome,
        email   : '[email protected]',
        items   : [
            new ReceiptItemDto(
                name    : 'Футболка синяя',
                price   : 150000,
                quantity: 1.0,
                amount  : 150000,
                tax     : VatEnum::None,
            ),
        ],
    ),
);

$response = $client->payment()->init($request);

if ($response->hasPaymentUrl()) {
    header('Location: ' . $response->paymentUrl);
    exit;
}

use TBank\Payments\DTO\Shared\ShopDto;

$request = new InitPaymentRequestDto(
    amount : 150000,
    orderId: 'order-2024-001',
    shops  : [
        new ShopDto(
            shopCode: '10001',
            amount  : 100000,
            name    : 'Футболка синяя',
            fee     : 2500,
        ),
        new ShopDto(
            shopCode: '10002',
            amount  : 50000,
            name    : 'Доставка',
        ),
    ],
);

use TBank\Payments\DTO\Request\ConfirmRequestDto;

$confirm = $client->payment()->confirm(
    new ConfirmRequestDto(paymentId: '123456789')
);

use TBank\Payments\DTO\Request\CancelRequestDto;

$cancel = $client->refund()->cancel(
    new CancelRequestDto(paymentId: '123456789')
);

$cancel = $client->refund()->cancel(
    new CancelRequestDto(paymentId: '123456789', amount: 50000)
);

use TBank\Payments\Enum\PaymentStatusEnum;

$state = $client->status()->getState('123456789');

if ($state->status === PaymentStatusEnum::Confirmed) {
    // Платёж подтверждён
}

if ($state->status->isSuccessful()) {
    // то же через метод enum
}

use TBank\Payments\DTO\Request\AddCardRequestDto;
use TBank\Payments\Enum\CardCheckTypeEnum;

$result = $client->card()->addCard(
    new AddCardRequestDto(
        customerKey: 'user-42',
        checkType  : CardCheckTypeEnum::Hold,
    )
);

header('Location: ' . $result->paymentUrl);

$request = new InitPaymentRequestDto(
    amount     : 99900,
    orderId    : 'sub-2024-05',
    customerKey: 'user-42',
    recurrent  : true,
);

$init = $client->payment()->init($request);

use TBank\Payments\Enum\{NotificationTypeEnum, PaymentStatusEnum};
use TBank\Payments\Exceptions\{InvalidWebhookPayloadException, InvalidWebhookSignatureException};

$handler = $client->webhookHandler();

try {
    $notification = $handler->handle(file_get_contents('php://input') ?: '');

    if (!$notification->success) {
        http_response_code(200);
        echo $handler->acknowledge();
        exit;
    }

    match ($notification->notificationType) {
        NotificationTypeEnum::Payment      => handlePayment($notification),
        NotificationTypeEnum::LinkCard     => handleLinkCard($notification),
        NotificationTypeEnum::Fiscalization => handleFiscalization($notification),
        default                            => null,
    };

    match ($notification->status) {
        PaymentStatusEnum::Confirmed         => handleConfirmed($notification),
        PaymentStatusEnum::Rejected          => handleRejected($notification),
        PaymentStatusEnum::PartialRefunded   => handlePartialRefund($notification),
        PaymentStatusEnum::Unknown           => logUnknownStatus($notification),
        default                              => null,
    };

    http_response_code(200);
    echo $handler->acknowledge();
} catch (InvalidWebhookSignatureException) {
    http_response_code(400);
    echo 'Bad signature';
} catch (InvalidWebhookPayloadException) {
    http_response_code(400);
    echo 'Bad payload';
}

use TBank\Payments\DTO\Request\RemoveCardRequestDto;

$cards = $client->card()->getCardList('user-42');

foreach ($cards->cards as $card) {
    echo "{$card->cardId}: {$card->pan}\n";
}

$client->card()->removeCard(
    new RemoveCardRequestDto(customerKey: 'user-42', cardId: '123456'),
);

$order = $client->status()->checkOrder('order-2024-001');

foreach ($order->payments as $payment) {
    echo "{$payment->paymentId}: {$payment->status->value}\n";
}

use TBank\Payments\DTO\Request\SendReceiptRequestDto;
use TBank\Payments\Enum\Fiscal\{PaymentMethodEnum, PaymentObjectEnum};

$client->receipt()->sendClosingReceipt(
    new SendReceiptRequestDto(
        paymentId: '123456789',
        receipt  : new ReceiptDto(
            taxation: TaxationEnum::UsnIncome,
            email   : '[email protected]',
            items   : [
                new ReceiptItemDto(
                    name         : 'Футболка синяя',
                    price        : 150000,
                    quantity     : 1.0,
                    amount       : 150000,
                    tax          : VatEnum::None,
                    paymentObject: PaymentObjectEnum::Commodity,
                    paymentMethod: PaymentMethodEnum::FullPayment,
                ),
            ],
        ),
    ),
);

use TBank\Payments\DTO\Request\FinishAuthorizeRequestDto;

$response = $client->payment()->finishAuthorize(
    new FinishAuthorizeRequestDto(
        paymentId: '123456789',
        md       : $_POST['MD'],
        paRes    : $_POST['PaRes'],
    ),
);

if ($response->

$client = new TBankClient(
    terminalKey: 'YOUR_TERMINAL_KEY',
    password   : 'YOUR_PASSWORD',
    environment: EnvironmentEnum::Test,
);

use TBank\Payments\DTO\Request\ChargeRequestDto;

$response = $client->payment()->charge(
    new ChargeRequestDto(
        paymentId: $init->paymentId,
        rebillId : $rebillIdFromWebhook,
    ),
);

use TBank\Payments\DTO\Request\GetQrRequestDto;
use TBank\Payments\Enum\QrDataTypeEnum;

$qr = $client->sbp()->getQr(
    new GetQrRequestDto(
        paymentId: $init->paymentId,
        dataType : QrDataTypeEnum::Payload,
    ),
);

echo $qr->data; // payload или SVG при QrDataTypeEnum::Image

use TBank\Payments\DTO\Request\AddCustomerRequestDto;

$client->customer()->add(
    new AddCustomerRequestDto(
        customerKey: 'user-42',
        email      : '[email protected]',
        phone      : '+79001234567',
    ),
);

$customer = $client->customer()->get('user-42');

$client->customer()->remove('user-42');

$state = $client->sbp()->getQrState($paymentId);

if ($state->status === PaymentStatusEnum::Confirmed) {
    // СБП-платёж подтверждён
}

use TBank\Payments\DTO\Request\AddAccountQrRequestDto;
use TBank\Payments\Enum\{AccountQrStatusEnum, NotificationTypeEnum, QrDataTypeEnum};

$binding = $client->sbp()->addAccountQr(
    new AddAccountQrRequestDto(
        description: 'Привязка счёта для автоплатежей',
        dataType   : QrDataTypeEnum::Payload,
    ),
);

// Показать QR: $binding->data
// Сохранить $binding->requestKey для проверки статуса

$state = $client->sbp()->getAddAccountQrState($binding->requestKey);

if ($state->status === AccountQrStatusEnum::Active) {
    // Счёт привязан; AccountToken придёт в webhook (NotificationType=QR)
}

if ($notification->notificationType === NotificationTypeEnum::Qr) {
    saveAccountToken($notification->accountToken);
}

use TBank\Payments\DTO\Request\GetQrBankListRequestDto;
use TBank\Payments\DTO\Shared\DeviceDto;
use TBank\Payments\Enum\DeviceTypeEnum;

$banks = $client->sbp()->getQrBankList(
    new GetQrBankListRequestDto(
        device: new DeviceDto(DeviceTypeEnum::Mobile, 'Android'),
    ),
);

foreach ($banks->bankList as $bank) {
    echo "{$bank->bankName}: {$bank->nspkBankId}\n";
}

use TBank\Payments\DTO\Request\ChargeQrRequestDto;

$response = $client->sbp()->chargeQr(
    new ChargeQrRequestDto(
        paymentId   : $init->paymentId,
        accountToken: $accountTokenFromWebhook,
    ),
);

use TBank\Payments\DTO\Request\ResendRequestDto;
use TBank\Payments\Enum\NotificationTypeEnum;

$result = $client->notifications()->resend(
    new ResendRequestDto(
        paymentId       : '123456789',
        notificationType: NotificationTypeEnum::Payment,
    ),
);

echo $result->count; // сколько уведомлений отправлено повторно

$client = new TBankClient(
    terminalKey      : 'YOUR_TERMINAL_KEY',
    password         : 'YOUR_PASSWORD',
    retryAttempts    : 3,    // до 3 попыток при NetworkException
    retryDelayMs     : 200,  // экспоненциальная задержка: 200, 400, 800… мс
    connectTimeout   : 10,   // таймаут установки соединения (сек)
    reuseConnection  : true, // persistent cURL share (FrankenPHP, RoadRunner)
);

use TBank\Payments\Http\{Psr18HttpClient, RetryingHttpClient};
use TBank\Payments\Enum\EnvironmentEnum;

$psr17 = new \Nyholm\Psr7\Factory\Psr17Factory();
$baseUrl = EnvironmentEnum::Production->baseUrl();

$client = new TBankClient(
    terminalKey: 'YOUR_TERMINAL_KEY',
    password   : 'YOUR_PASSWORD',
    environment: EnvironmentEnum::Production,
    httpClient : new RetryingHttpClient(
        inner       : new Psr18HttpClient(
            client        : $psr18Client,
            requestFactory: $psr17,
            streamFactory : $psr17,
            baseUrl       : $baseUrl,
        ),
        maxAttempts : 3,
        delayMs     : 200,
    ),
);

$client = new TBankClient(
    terminalKey  : 'YOUR_TERMINAL_KEY',
    password     : 'YOUR_PASSWORD',
    retryAttempts: 3,
    retryDelayMs : 200,
);

use TBank\Payments\Http\Psr18HttpClient;
use TBank\Payments\Enum\EnvironmentEnum;

$psr17 = new \Nyholm\Psr7\Factory\Psr17Factory();

$client = new TBankClient(
    terminalKey: 'YOUR_TERMINAL_KEY',
    password   : 'YOUR_PASSWORD',
    environment: EnvironmentEnum::Production,
    httpClient : new Psr18HttpClient(
        client        : $psr18Client,      // Guzzle или Symfony HttpClient
        requestFactory: $psr17,
        streamFactory : $psr17,
        baseUrl       : EnvironmentEnum::Production->baseUrl(),
    ),
);

use TBank\Payments\Exceptions\{ApiException, NetworkException, TBankException};

try {
    $response = $client->payment()->init($request);
} catch (ApiException $e) {
    echo $e->getMessage();
    echo $e->getErrorCode();
} catch (NetworkException $e) {
    echo $e->getMessage();
} catch (TBankException $e) {
    // прочие ошибки пакета
}

bash
composer install
php examples/01-init-payment.php
php examples/05-cards.php list user-42
php examples/08-check-status.php payment 123456789

src/
├── TBankClient.php
├── TokenGenerator.php
├── WebhookHandler.php
├── Enum/
│   ├── PaymentStatusEnum.php
│   ├── PayTypeEnum.php
│   ├── LanguageEnum.php
│   ├── CardCheckTypeEnum.php
│   ├── EnvironmentEnum.php
│   ├── NotificationTypeEnum.php
│   ├── QrDataTypeEnum.php
│   ├── DeviceTypeEnum.php
│   ├── AccountQrStatusEnum.php
│   ├── Fiscal/              # TaxationEnum, VatEnum, PaymentObjectEnum, …
│   └── Card/                # CardStatusEnum, CardTypeEnum
├── Api/
├── DTO/
│   ├── Request/
│   ├── Response/
│   ├── Shared/
│   └── WebhookNotificationDto.php
├── Http/
│   ├── HttpClient.php
│   ├── HttpClientContract.php
│   ├── RetryingHttpClient.php
│   ├── Psr18HttpClient.php
│   └── JsonResponseParser.php
├── Support/                 # ApiUrlBuilder, ApiValueParser
└── Exceptions/
    ├── TBankException.php
    ├── ApiException.php
    ├── NetworkException.php
    ├── InvalidWebhookSignatureException.php
    └── InvalidWebhookPayloadException.php