T-Банк (T-Kassa)

T-Kassa — merchant acquiring от Т-Банка. Принимает карты и СБП-QR в одном API. Аналог ЮKassa, популярен у новых ИП и ООО’шек из-за быстрой онбординг-процедуры Т-Банка.

1. Credentials

В личном кабинете Т-Банк → «Интернет-эквайринг» → «Настройки»:

TerminalKey — идентификатор терминала (публичный)
Password — секретный пароль терминала (держите в секрете)

2. Сохраните в OPORA

Settings → Secrets:

tbank-terminal-key: ваш TerminalKey
tbank-password: ваш Password

3. Ноды

Нода	Что делает
`tbank.webhook.trigger`	Incoming события (авторизация / захват / отмена / refund)
`tbank.payment.init`	Создание платежа → вернёт `PaymentURL` для редиректа клиента
`tbank.payment.get`	Статус по `PaymentId`
`tbank.payment.qr`	Получить SBP-QR для этого платежа
`tbank.payment.cancel`	Отмена / refund (unified — в T-Kassa это одна операция)

4. Пример: order → payment URL

webhook.trigger
  {order_id, amount_rub, description}
    ↓
tbank.payment.init
  OrderId = "{{trigger.order_id}}"
  Amount = {{trigger.amount_rub * 100}}    # копейки!
  Description = "{{trigger.description}}"
  NotificationURL = "https://app.opora.example/webhook/<uuid>"
    ↓
# Отдать клиенту tbank.payment.init.result.PaymentURL

5. SBP-QR

Два пути:

a) QR на этапе оплаты — пользователь сканирует QR в своём банковском приложении вместо ввода карты:

tbank.payment.init
  ... (как выше)
  PayType = "O"  # one-stage
    ↓
tbank.payment.qr
  PaymentId = "{{init.result.PaymentId}}"
  DataType = "PAYLOAD"  # или "IMAGE" для base64 SVG

tbank.payment.qr вернёт SBP-URL (https://qr.nspk.ru/AS...) или base64-encoded SVG картинку. Фронтенд рендерит её.

b) QR вместо карты — клиент в кассе показывает QR со своего телефона (кассир сканирует) — другой flow, не покрывается OPORA’ой.

6. Webhook handling

tbank.webhook.trigger
    ↓
control.switch (on: {{trigger.Status}})
  ├─ "AUTHORIZED" → одобрен, ждёт capture
  ├─ "CONFIRMED"  → захвачен, деньги у мерчанта
  ├─ "REFUNDED"   → возврат прошёл
  └─ "REJECTED"   → отказ банка / мошенничество

Подпись webhook’а — Token-based (SHA-256 над отсортированными полями + password). OPORA валидирует автоматически, используя tbank-password secret.

7. Two-stage (auth + capture)

tbank.payment.init
  ... PayType = "T"  # T = two-stage
    ↓
# После AUTHORIZED webhook'а — когда товар отгружен:
tbank.payment.confirm   # API note: в коде это tbank.payment.capture
  PaymentId = "{{payment_id}}"
  Amount = {{actual_captured_amount * 100}}

Не захватил за 7 дней → T-Kassa автоматически отменит.

Troubleshooting

`INVALID_TOKEN_PARAMETERS`

Подпись не сошлась. Проверьте что tbank-password secret совпадает с Password в кабинете T-Kassa (регистр важен; не путайте с паролем личного кабинета — это разные пароли).

`ORDER_EXISTS`

T-Kassa не даёт создать платёж с тем же OrderId. Либо используйте уникальные (например, order_id + "_" + timestamp), либо сначала tbank.payment.get с OrderId-фильтром, чтобы подобрать существующий.

SBP-QR не сканируется

QR от Т-Банка подходит только СБП-compatible банкам (большинство, но не все). Проверьте в мобильном банке клиента — есть ли «Платежи по QR».

Webhook приходит дважды

T-Kassa ретраит до 200 OK. Если OPORA ответила 5xx’ом — получите дубликат через 5 минут. Используйте data_table.rows.upsert с уникальным PaymentId чтобы idempotent’но обрабатывать повторы.

Связанное

ЮKassa — альтернатива, шире rollout на рынке (в том числе секция «СБП-QR» для сравнения реализаций)