PHPackages                             webmasterolegan/tbank-payments - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. webmasterolegan/tbank-payments

ActiveLibrary

webmasterolegan/tbank-payments
==============================

PHP 8.5+ SDK для работы с API интернет-эквайринга T-Bank (Тинькофф)

v0.9.0(1w ago)04↑2900%MITPHP ^8.5

Since Jul 12Compare

[ Source](https://github.com/webmasterolegan/tbank-payments)[ Packagist](https://packagist.org/packages/webmasterolegan/tbank-payments)[ RSS](/packages/webmasterolegan-tbank-payments/feed)WikiDiscussions Synced today

READMEChangelogDependencies (5)Versions (2)Used By (0)

tbank-payments
==============

[](#tbank-payments)

PHP 8.5+ SDK для работы с API интернет-эквайринга **T-Bank** (бывший Tinkoff).

[![PHP 8.5+](https://camo.githubusercontent.com/2788132aa1e54031a6c94edcbf8688566d3e18cb5492cd1766836f74a24b27b5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e352532422d626c75652e737667)](https://php.net)[![License: MIT](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

---

Возможности
-----------

[](#возможности)

ГруппаМетодыПлатежиInit, FinishAuthorize, Confirm, ChargeСБПGetQr, GetQrState, GetQrBankList, QrMembersList, ChargeQr, AddAccountQr, GetAddAccountQrStateСтатусGetState, CheckOrderУведомленияResendОтмена / возвратCancel (полный и частичный)КартыAddCard, GetCardList, RemoveCardПокупателиAddCustomer, GetCustomer, RemoveCustomerЧеки (ФФД 1.2)SendClosingReceiptWebhookВалидация подписи, типизированное уведомление---

Установка
---------

[](#установка)

```
composer require webmasterolegan/tbank-payments
```

**Требования:** PHP ≥ 8.5, расширения `curl`, `json`, `uri`.

---

Быстрый старт
-------------

[](#быстрый-старт)

```
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,
);
```

### 1. Инициировать платёж

[](#1-инициировать-платёж)

```
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   : 'buyer@example.com',
        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;
}
```

### 2. Подтвердить двухстадийное списание

[](#2-подтвердить-двухстадийное-списание)

```
use TBank\Payments\DTO\Request\ConfirmRequestDto;

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

### 3. Отменить / вернуть платёж

[](#3-отменить--вернуть-платёж)

```
use TBank\Payments\DTO\Request\CancelRequestDto;

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

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

### 4. Получить статус платежа

[](#4-получить-статус-платежа)

```
use TBank\Payments\Enum\PaymentStatusEnum;

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

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

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

### 5. Привязать карту

[](#5-привязать-карту)

```
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);
```

### 6. Оплата по привязанной карте (рекуррент)

[](#6-оплата-по-привязанной-карте-рекуррент)

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

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

### 7. Обработка webhook

[](#7-обработка-webhook)

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

$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';
}
```

### 8. Список и удаление карт

[](#8-список-и-удаление-карт)

```
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'),
);
```

### 9. Статус заказа (несколько платежей)

[](#9-статус-заказа-несколько-платежей)

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

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

### 10. Закрывающий чек

[](#10-закрывающий-чек)

```
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   : 'buyer@example.com',
            items   : [
                new ReceiptItemDto(
                    name         : 'Футболка синяя',
                    price        : 150000,
                    quantity     : 1.0,
                    amount       : 150000,
                    tax          : VatEnum::None,
                    paymentObject: PaymentObjectEnum::Commodity,
                    paymentMethod: PaymentMethodEnum::FullPayment,
                ),
            ],
        ),
    ),
);
```

### 11. FinishAuthorize (3DS, своя форма)

[](#11-finishauthorize-3ds-своя-форма)

```
use TBank\Payments\DTO\Request\FinishAuthorizeRequestDto;

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

if ($response->requires3ds()) {
    // Редирект на ACS: $response->acsUrl
}
```

### 12. Тестовая среда

[](#12-тестовая-среда)

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

### 13. Списание по RebillId (Charge)

[](#13-списание-по-rebillid-charge)

```
use TBank\Payments\DTO\Request\ChargeRequestDto;

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

### 14. Оплата через СБП (GetQr)

[](#14-оплата-через-сбп-getqr)

```
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
```

### 15. Покупатели

[](#15-покупатели)

```
use TBank\Payments\DTO\Request\AddCustomerRequestDto;

$client->customer()->add(
    new AddCustomerRequestDto(
        customerKey: 'user-42',
        email      : 'user@example.com',
        phone      : '+79001234567',
    ),
);

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

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

### 16. Статус СБП-платежа (GetQrState)

[](#16-статус-сбп-платежа-getqrstate)

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

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

### 17. Привязка счёта СБП (AddAccountQr)

[](#17-привязка-счёта-сбп-addaccountqr)

```
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)
}
```

В webhook-уведомлении типа `QR` доступны поля `accountToken` и `requestKey`:

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

### 18. Список банков СБП (GetQrBankList)

[](#18-список-банков-сбп-getqrbanklist)

```
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";
}
```

### 19. Автоплатёж СБП (ChargeQr)

[](#19-автоплатёж-сбп-chargeqr)

```
use TBank\Payments\DTO\Request\ChargeQrRequestDto;

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

### 20. Повторная отправка уведомлений (Resend)

[](#20-повторная-отправка-уведомлений-resend)

```
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; // сколько уведомлений отправлено повторно
```

### 21. Повтор при сетевых ошибках и переиспользование cURL

[](#21-повтор-при-сетевых-ошибках-и-переиспользование-curl)

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

### 22. PSR-18 HTTP-клиент с retry

[](#22-psr-18-http-клиент-с-retry)

По умолчанию SDK использует cURL. Для интеграции с Guzzle или Symfony HttpClient:

```
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,
    ),
);
```

Альтернатива — встроенный retry через конструктор `TBankClient` (работает с любым `HttpClientContract`):

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

Без обёртки — только cURL:

```
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(),
    ),
);
```

---

Примеры (examples/)
-------------------

[](#примеры-examples)

В каталоге `examples/` — готовые скрипты. Перед запуском задайте переменные окружения:

```
export TBANK_TERMINAL_KEY=your_terminal_key
export TBANK_PASSWORD=your_password
export TBANK_ENV=production   # или test
```

СкриптОписание`01-init-payment.php`Одностадийный платёж с чеком`02-two-step-payment.php`Двухстадийный платёж (холд + Confirm)`03-finish-authorize-3ds.php`Завершение 3DS (MD + PaRes)`04-webhook-endpoint.php`Обработчик NotificationURL`05-cards.php`Привязка, список, удаление карт`06-refund.php`Полный и частичный возврат`07-receipt.php`Закрывающий чек`08-check-status.php`Статус платежа и заказа`09-recurrent-payment.php`Рекуррентный платёж`10-charge.php`Списание по RebillId`11-sbp-payment.php`Init + GetQr (СБП)`12-customer.php`Регистрация и получение покупателя`13-sbp-qr-state.php`Статус СБП-платежа`14-sbp-bank-list.php`Список банков СБП`15-resend.php`Повторная отправка уведомлений`16-sbp-account-binding.php`Привязка счёта + автоплатёж СБП```
composer install
php examples/01-init-payment.php
php examples/05-cards.php list user-42
php examples/08-check-status.php payment 123456789
```

---

Архитектура пакета
------------------

[](#архитектура-пакета)

**Соглашения об именовании:** DTO — суффикс `Dto`, enum — `Enum`, интерфейсы — `Contract`.

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

```

---

Обработка ошибок
----------------

[](#обработка-ошибок)

```
use TBank\Payments\Exceptions\{ApiException, InvalidWebhookSignatureException, 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) {
    // прочие ошибки пакета
}
```

---

Запуск тестов
-------------

[](#запуск-тестов)

```
composer install
composer ci      # тесты + PHPStan
composer test
```

---

Ссылки
------

[](#ссылки)

- [Документация T-Bank API](https://developer.tbank.ru/eacq/api/priem-platezhei)
- [Формирование токена](https://developer.tbank.ru/eacq/intro/developer/token)
- [Уведомления об операциях](https://developer.tbank.ru/eacq/intro/developer/notification)
- [Личный кабинет эквайринга](https://business.tbank.ru/oplata/main)

---

Лицензия
--------

[](#лицензия)

MIT © Oleg Polyakov

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance98

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

8d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e69553fc67c54666833c6c9a062e8262faa5c089a9e8c3db2ebbbf8c8d08f0a3?d=identicon)[webmasterolegan](/maintainers/webmasterolegan)

---

Tags

sdkpaymentsacquiringtinkofftbank

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/webmasterolegan-tbank-payments/health.svg)

```
[![Health](https://phpackages.com/badges/webmasterolegan-tbank-payments/health.svg)](https://phpackages.com/packages/webmasterolegan-tbank-payments)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60216.0M89](/packages/mollie-mollie-api-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[chargebee/chargebee-php

ChargeBee API client implementation for PHP

758.5M9](/packages/chargebee-chargebee-php)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6942.5M425](/packages/drupal-core-recommended)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

1003.9M50](/packages/getbrevo-brevo-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)