T-Банк (T-Kassa)

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

1. Credentials#

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

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

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

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://api.summing.org/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, не покрывается SUMMING'ой.

6. Webhook handling#

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

Подпись webhook'а — Token-based (SHA-256 над отсортированными полями + password). SUMMING валидирует автоматически, используя 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. Если SUMMING ответила 5xx'ом — получите дубликат через 5 минут. Используйте data_table.rows.upsert с уникальным PaymentId чтобы idempotent'но обрабатывать повторы.

Связанное#

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