README

Мост (bridge) между noith/payment-core и эквайрингом T‑Bank (Тинькофф) для Laravel. Пакет подключает платёжные «рельсы» T‑Bank к ядру payment-core: создание счетов, синхронизация статусов, приём вебхуков и рекуррентные платежи.

Под капотом используется HTTP‑клиент noith/tbank.

Возможности

• Карты (tbank) — оплата картой с редиректом, рекуррентные платежи (rebill).
• СБП (tbank-sbp) — оплата через Систему быстрых платежей, привязка счёта (account binding).
• T‑Pay (tbank-tpay).
• Mir Pay (tbank-mir).
• Синхронизация статусов (GetState) и сверка (reconciliation).
• Приём вебхуков-уведомлений на готовый маршрут.
• Фискализация чеков через фискальный профиль продавца из payment-core.
• Валюта: RUB.

Требования

• PHP ^8.3
• Laravel (через noith/payment-core ^1.0.6)
• noith/tbank ^1.1

Установка

composer require noith/tbank-bridge

Пакет использует Laravel package discovery — TbankServiceProvider подключается автоматически. Он регистрирует платёжные системы в PaymentSystemRegistry и добавляет маршрут вебхука.

(Опционально) опубликуйте конфиг:

php artisan vendor:publish --tag=tbank-config

Конфигурация

После публикации появится config/tbank.php. Все значения берутся из env:

return [
    // Базовые URL эквайринга (можно переопределить per-seller, см. ниже).
    'api_url'      => env('TBANK_API_URL', 'https://securepay.tinkoff.ru/v2/'),
    'cashbox_url'  => env('TBANK_CASHBOX_URL', 'https://securepay.tinkoff.ru/cashbox/'),

    // Маршрут для приёма вебхуков от T-Bank.
    'webhook_path'       => env('TBANK_WEBHOOK_PATH', 'payment/tbank/webhook'),
    'webhook_middleware' => [],
];

В .env:

# Боевые значения по умолчанию уже стоят в конфиге — переопределяйте только при необходимости
# (например, для теста подставьте sandbox-URL T-Bank).
TBANK_API_URL=https://securepay.tinkoff.ru/v2/
TBANK_CASHBOX_URL=https://securepay.tinkoff.ru/cashbox/
TBANK_WEBHOOK_PATH=payment/tbank/webhook

⚠️ Терминальные ключи (terminal_key / secret_key) не хранятся в этом конфиге. Они задаются per‑seller в payment-core (см. раздел «Учётные данные продавца»).

Учётные данные продавца

Ключи терминала хранятся per‑seller в payment-core (в credentials записи payment_credentials). TbankCredentials::fromArray() ожидает:

Так разные продавцы могут работать на разных терминалах (и при необходимости — на разных окружениях), а сами ключи никогда не попадают в код или репозиторий.

Вебхуки

Сервис‑провайдер регистрирует POST‑маршрут:

• путь: webhook_path (по умолчанию payment/tbank/webhook);
• имя: tbank.webhook;
• middleware: из webhook_middleware.

Этот URL по умолчанию подставляется в NotificationURL при создании платежа (если не задан кастомный резолвер, см. ниже). Укажите его в настройках терминала в личном кабинете T‑Bank или положитесь на значение, отправляемое в Init.

Return / Notification URL

URL'ы, отправляемые в Init (SuccessURL, FailURL, NotificationURL), часто зависят от конкретного счёта (подписанные ссылки, параметры маршрута), поэтому их нельзя задать статикой. Зарегистрируйте резолверы в boot() своего сервис‑провайдера:

use Noith\Payment\Models\PaymentInvoice;
use Noith\PaymentTbank\Support\TbankUrls;

public function boot(): void
{
    TbankUrls::successUrlUsing(fn (PaymentInvoice $i) => route('shop.paid', $i->uuid));
    TbankUrls::failUrlUsing(fn (PaymentInvoice $i) => route('shop.failed', $i->uuid));

    // Необязательно: по умолчанию NotificationURL = route('tbank.webhook').
    TbankUrls::notificationUrlUsing(fn (PaymentInvoice $i) => route('tbank.webhook'));
}

Резолвер может вернуть null — тогда значение не отправляется и применяются настройки самого терминала. NotificationURL по умолчанию указывает на встроенный маршрут вебхука пакета.

Использование

Платёжные системы регистрируются в payment-core под кодами:

Создание счёта и работа с ним выполняются через API payment-core — выбирайте нужный код платёжной системы. Бридж сам формирует Init‑запрос, возвращает RedirectInvoiceResult со ссылкой на оплату и проставляет provider_invoice_id.

Рекуррентные платежи

• Карты: при save_payment_method на счёте отправляется Recurrent, а RebillId из вебхука сохраняется как токен метода оплаты и используется для последующих списаний.
• СБП: используется привязка счёта (AccountToken).

Тесты

composer test

Лицензия

MIT.