tbank-payments

v1.2.1

Published

2 months ago

Библиотека для интеграции с API T-Bank эквайринг. Поддерживает платежи картами, СБП, рекуррентные платежи, управление клиентами и картами, QR-коды.

0High
0Medium
0Low

esurkov1

tbank tinkoff acquiring payments ecommerce sbp qr russia api

T-Bank Payments

Официальная документация: https://developer.tbank.ru/eacq/api

Полная библиотека для интеграции с T-Bank Acquiring API (ранее Тинькофф). Поддерживает 100% методов API для приема платежей, включая:

💳 Платежи банковскими картами
📱 T-Pay, SberPay, Mir Pay, Система быстрых платежей (СБП)
🔗 Привязка счета СБП или карты для автоплатежей
📋 Рекуррентные платежи по сохраненным реквизитам (COF-операции) (СБП/карты)
👥 Управление клиентами
💾 Управление привязанными картами
🔲 QR-коды для оплаты
🧾 Чеки (54-ФЗ)
🔐 Методы для работы с 3DS

Introduction

Установка

npm install tbank-payments

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

const TbankPayments = require('tbank-payments');

const tbank = new TbankPayments({
  merchantId: 'YOUR_TERMINAL_KEY',
  secret: 'YOUR_SECRET_KEY',
});

// Простой платеж
const payment = await tbank.initPayment({
  Amount: TbankPayments.amountToKopecks(100), // 100 рублей в копейках
  OrderId: 'order-123',
  Description: 'Оплата заказа #123',
  SuccessURL: 'https://yoursite.com/success',
  FailURL: 'https://yoursite.com/fail',
});

console.log('Payment URL:', payment.PaymentURL);

Проведение платежа

Инициировать платеж

Метод создает новый платеж и возвращает URL для перенаправления клиента на страницу оплаты.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/init

const payment = await tbank.initPayment({
  Amount: 50000, // 500 рублей в копейках
  OrderId: 'unique-order-id',
  Description: 'Описание товара/услуги',
  CustomerKey: 'customer-123', // для рекуррентных платежей
  Receipt: {
    Email: '[email protected]',
    Taxation: 'osn',
    Items: [
      {
        Name: 'Товар',
        Price: 50000,
        Quantity: 1,
        Tax: 'vat20',
      },
    ],
  },
  SuccessURL: 'https://yoursite.com/success',
  FailURL: 'https://yoursite.com/fail',
  NotificationURL: 'https://yoursite.com/webhook',
});

Подтвердить платеж

Метод подтверждает двухстадийный платеж.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/confirm

const result = await tbank.confirmPayment({
  PaymentId: payment.PaymentId,
  Amount: 50000, // необязательно, можно подтвердить частично
});

Подтвердить списание

Метод подтверждает списание средств.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/confirm-debit

const result = await tbank.confirmDebit({
  PaymentId: payment.PaymentId,
  Amount: 50000,
});

Прием платежей по карте

Завершение авторизации

Метод завершает авторизацию платежа с данными карты.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/finish-authorize

const result = await tbank.finishAuthorize({
  PaymentId: payment.PaymentId,
  CardData: encryptedCardData,
  SendEmail: true,
  InfoEmail: '[email protected]',
});

Методы для работы с 3DS

Проверить версию 3DS

Метод возвращает версию протокола 3DS, по которому может аутентифицироваться карта.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/check-3-ds-version

const version = await tbank.check3dsVersion({
  PaymentId: payment.PaymentId,
  CardData: 'PAN=4300000000000777;ExpDate=0519;CardHolder=IVAN PETROV;CVV=111',
});

Пройти этап 3DS Method

Метод для сбора информации ACS-ом о девайсе.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/3-ds-method

const result = await tbank.submit3DSMethod({
  threeDSMethodData: base64EncodedData,
});

Отправить запрос в банк-эмитент для прохождения 3DS

Метод отправляет запрос в банк-эмитент для прохождения 3DS аутентификации.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/acs-url

const result = await tbank.submit3DSAuthorization({
  PaymentId: payment.PaymentId,
  MD: mdValue,
  PaRes: paResValue,
});

Подтвердить прохождение 3DS v1.0

Метод подтверждает прохождение 3DS версии 1.0.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/submit-3-ds-authorization-v-1

const result = await tbank.confirm3DSv1({
  PaymentId: payment.PaymentId,
  MD: mdValue,
  PaRes: paResValue,
});

Подтвердить прохождение 3DS v2.1

Метод подтверждает прохождение 3DS версии 2.1.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/submit-3-ds-authorization-v-2

const result = await tbank.confirm3DSv2({
  PaymentId: payment.PaymentId,
  Cres: cresValue,
});

Другие способы приема платежей

СБП (Система быстрых платежей)

Сформировать QR

Метод формирует QR-код для оплаты через СБП.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-qr

const qr = await tbank.getQr({
  PaymentId: payment.PaymentId,
  DataType: 'PAYLOAD', // или 'IMAGE' для base64 изображения
});

Получить статус QR-кода

Метод возвращает статус QR-платежа.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-qr-state

const qrStatus = await tbank.getQrState({
  PaymentId: payment.PaymentId,
});

Получить список банков-пользователей QR для возврата

Метод возвращает список банков для возврата средств через QR.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-qr-bank-list

const banks = await tbank.getQrBankList();

Привязать счет к магазину

Метод инициирует процесс привязки счета клиента через СБП для автоплатежей.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/add-account

const account = await tbank.addAccount({
  CustomerKey: 'customer-123',
  Description: 'Привязка счета для автоплатежей',
  SuccessURL: 'https://yoursite.com/success',
  FailURL: 'https://yoursite.com/fail',
  NotificationURL: 'https://yoursite.com/webhook',
});

Получить статус привязки счета к магазину

Метод проверяет статус привязки счета.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-add-account-state

const status = await tbank.getAddAccountState({
  RequestKey: 'request-key-from-notification',
});

Получить список счетов, привязанных к магазину

Метод возвращает список всех привязанных счетов.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-account-qr-list

const accounts = await tbank.getAccountQrList();

Создать тестовую платежную сессию

Метод создает тестовую сессию для тестирования СБП платежей.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/sbp-pay-test

const test = await tbank.sbpPayTest({
  PaymentId: payment.PaymentId,
  IsDeadlineExpired: false,
  IsRejected: false,
});

Получить список банков-участников СБП для платежа

Метод возвращает список банков-участников СБП.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/qr-members-list

const members = await tbank.getQrMembersList();

T-Pay

Определить возможность проведения платежа

Метод определяет возможность проведения платежа T-Pay на терминале.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/status

const status = await tbank.getTPayStatus();

Получить ссылку

Метод генерирует ссылку для безусловного редиректа на мобильных устройствах.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/link

const link = await tbank.getTPayLink({
  paymentId: payment.PaymentId,
  version: '2.0',
});

Получить QR

Метод генерирует QR для десктопов.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/qr

const qr = await tbank.getTPayQr({
  paymentId: payment.PaymentId,
});

SberPay

Получить QR

Метод генерирует QR-код для оплаты через SberPay.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/sber-pay-qr

const qr = await tbank.getSberPayQr({
  paymentId: payment.PaymentId,
});

Получить ссылку

Метод генерирует ссылку для оплаты через SberPay.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/sber-paylink

const link = await tbank.getSberPayLink({
  paymentId: payment.PaymentId,
  version: '2.0',
});

Mir Pay

Получить DeepLink

Метод генерирует DeepLink для оплаты через Mir Pay.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-deep-link

const deepLink = await tbank.getMirPayDeepLink({
  PaymentId: payment.PaymentId,
});

Привязка карты

Методы работы с клиентами

Зарегистрировать клиента

Метод регистрирует нового клиента в системе.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/add-customer

const customer = await tbank.addCustomer({
  CustomerKey: 'customer-123',
  Email: '[email protected]',
  Phone: '+79001234567',
});

Получить данные клиента

Метод возвращает данные зарегистрированного клиента.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-customer

const customer = await tbank.getCustomer({
  CustomerKey: 'customer-123',
});

Удалить данные клиента

Метод удаляет данные клиента из системы.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/remove-customer

await tbank.removeCustomer({
  CustomerKey: 'customer-123',
});

Методы работы с картами

Инициировать привязку карты к клиенту

Метод инициирует процесс привязки карты к клиенту.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/add-card

const cardRequest = await tbank.addCard({
  CustomerKey: 'customer-123',
  CheckType: '3DS',
});

Привязать карту

Метод привязывает карту к клиенту.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/attach-card

const result = await tbank.attachCard({
  RequestKey: cardRequest.RequestKey,
  CardData: encryptedCardData,
});

Получить статус привязки карты

Метод проверяет статус процесса привязки карты.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-add-card-state

const status = await tbank.getAddCardState({
  RequestKey: cardRequest.RequestKey,
});

Получить список карт клиента

Метод возвращает список всех привязанных карт клиента.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-card-list

const cards = await tbank.getCardList({
  CustomerKey: 'customer-123',
});

Удалить привязанную карту клиента

Метод удаляет привязанную карту клиента.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/remove-card

await tbank.removeCard({
  CustomerKey: 'customer-123',
  CardId: 'card-id',
});

Проведение платежа по сохраненным реквизитам

Провести платеж по сохраненным реквизитам

Метод проводит платеж с использованием ранее сохраненных реквизитов карты.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/charge

const recurrentPayment = await tbank.chargeRecurrent({
  PaymentId: newPayment.PaymentId,
  RebillId: previousPayment.RebillId,
});

Автоплатеж по QR СБП

Метод проводит автоплатеж через СБП с использованием привязанного счета.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/charge-qr

const autopay = await tbank.chargeQr({
  PaymentId: payment.PaymentId,
  AccountToken: 'account-token-from-addAccount-notification',
  SendEmail: true,
  InfoEmail: '[email protected]',
});

Отмена платежа

Отменить платеж

Метод отменяет платеж полностью или частично.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/cancel

const result = await tbank.cancelPayment({
  PaymentId: payment.PaymentId,
  Amount: 25000, // частичная отмена
});

Статус платежа или заказа

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

Метод возвращает текущий статус платежа.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/status

const status = await tbank.getPaymentState({
  PaymentId: payment.PaymentId,
});

console.log('Status:', status.Status);
console.log('Amount:', TbankPayments.kopecksToAmount(status.Amount));

Получить статус заказа

Метод возвращает статус всех платежей по заказу.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/check-order

const orderStatus = await tbank.checkOrder({
  OrderId: 'order-123',
});

Справка по операции

Получить справку по операции

Метод генерирует справку по операции для конкретного платежа или списка платежей.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/get-confirm-operation

// Отправка справки на email
const receipt = await tbank.getConfirmOperation({
  PaymentIdList: [12345678, 12345679],
  EmailList: ['[email protected]'],
});

// Получение справки через callback URL
const receiptCallback = await tbank.getConfirmOperation({
  PaymentIdList: [12345678],
  CallbackUrl: 'https://yoursite.com/receipt-callback',
});

Методы работы с чеками

Отправить закрывающий чек в кассу

Метод отправляет закрывающий чек (чек возврата или коррекции) в кассу.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/send-closing-receipt

const receipt = await tbank.sendClosingReceipt({
  PaymentId: 12345678,
  Receipt: {
    Email: '[email protected]',
    Taxation: 'osn',
    Items: [
      {
        Name: 'Возврат товара',
        Price: 10000,
        Quantity: 1,
        Amount: 10000,
        Tax: 'vat20',
      },
    ],
  },
});

Получить статус отправки чека

Метод проверяет статус отправки чека в кассу.

Ссылка на документацию: https://developer.tbank.ru/eacq/api/metodi-raboti-s-chekami

const receiptStatus = await tbank.getReceiptState({
  PaymentId: 12345678,
});

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

Библиотека использует кастомные классы ошибок для удобной обработки:

try {
  await tbank.initPayment({
    Amount: 50000,
    OrderId: 'order-123',
  });
} catch (error) {
  if (error.name === 'TbankApiError') {
    console.error('API Error:', error.code, error.message);
    console.error('Details:', error.details);
  } else if (error.name === 'TbankValidationError') {
    console.error('Validation Error:', error.message);
  } else if (error.name === 'TbankNetworkError') {
    console.error('Network Error:', error.message);
  }
}

Webhook уведомления

Проверка подписи webhook

// В вашем webhook endpoint
app.post('/webhook', (req, res) => {
  const notification = req.body;
  const receivedToken = notification.Token;

  // Проверяем подпись
  if (tbank.verifyNotificationSignature(notification, receivedToken)) {
    console.log('Valid notification:', notification.Status);

    // Обрабатываем уведомление
    switch (notification.Status) {
      case 'CONFIRMED':
        // Платеж успешно подтвержден
        break;
      case 'REJECTED':
        // Платеж отклонен
        break;
    }

    res.send('OK');
  } else {
    res.status(400).send('Invalid signature');
  }
});

Тестирование

Для тестирования используйте тестовые реквизиты из документации T-Bank.

Тест-кейсы

Ссылка на документацию: https://developer.tbank.ru/eacq/intro/errors/test-cases

Для прохождения тест-кейсов используйте тестовый терминал с приставкой DEMO. Запросы с него нужно отправлять на боевую среду — https://securepay.tinkoff.ru/v2.

Важно:

При тестировании платежей в методе Инициировать платеж нельзя передавать параметры, которые противоречат настройкам терминала
В запросе метода Инициировать платеж не нужно передавать Recurrent = Y — признак родительского рекуррентного платежа не позволит пройти тест-кейс
При получении ошибки «Ошибка уведомлении: не получаем ответ ОК на следующие уведомлении: REJECTED» проверьте правильность передачи ответа на уведомление. Верный ответ — 200:ОК, без тегов, заглавными английскими буквами

Тестирование СБП

Ссылка на документацию: https://developer.tbank.ru/eacq/intro/errors/test-sbp

Доступны следующие сценарии:

Платеж — успех
Платеж — отказ по таймауту
Платеж — отказ, отклонен со стороны Т-Бизнеса
Возврат — успех

Коды ошибок

Ссылка на документацию: https://developer.tbank.ru/eacq/intro/errors/error-codes

Библиотека включает маппинг кодов ошибок из официальной документации. Используйте lib/test-data/test-scenarios.js для доступа к кодам ошибок в тестах.

Ошибки 3DS

Ссылка на документацию: https://developer.tbank.ru/eacq/intro/errors/3ds

При работе с методами 3DS могут возникать специфичные ошибки. Все коды ошибок 3DS доступны в lib/test-data/test-scenarios.js.

Ошибки онлайн-кассы

Ссылка на документацию: https://developer.tbank.ru/eacq/intro/errors/kassa

При работе с чеками могут возникать ошибки кассы. Все коды ошибок доступны в lib/test-data/test-scenarios.js.

Вспомогательные методы

Создание чека

const receipt = tbank.createReceipt({
  email: '[email protected]',
  phone: '+79001234567', // необязательно
  taxation: 'osn',
  items: [
    {
      name: 'Товар 1',
      price: 30000, // в копейках
      quantity: 1,
      tax: 'vat20',
    },
    {
      name: 'Товар 2',
      price: 20000,
      quantity: 2,
      tax: 'vat10',
      ean13: '1234567890123',
    },
  ],
});

Конвертация сумм

// Рубли в копейки
const kopecks = TbankPayments.amountToKopecks(100.5); // 10050

// Копейки в рубли
const rubles = TbankPayments.kopecksToAmount(10050); // 100.5

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

Параметры конструктора

const tbank = new TbankPayments({
  merchantId: 'YOUR_TERMINAL_KEY', // Ключ терминала (обязательно)
  secret: 'YOUR_SECRET_KEY', // Секретный ключ (обязательно)
  apiUrl: 'https://securepay.tinkoff.ru', // URL API (необязательно)
  logger: customLogger, // Кастомный логгер (необязательно)
  retryConfig: {
    // Настройки retry (необязательно)
    retries: 3,
    retryDelay: axiosRetry.exponentialDelay,
  },
});

Настройка логирования

const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [new winston.transports.File({ filename: 'tbank.log' })],
});

const tbank = new TbankPayments({
  merchantId: 'YOUR_TERMINAL_KEY',
  secret: 'YOUR_SECRET_KEY',
  logger: logger,
});

Статусы платежей

| Статус | Описание | | ------------------ | ----------------------------------- | | NEW | Платеж создан | | FORM_SHOWED | Показана форма оплаты | | AUTHORIZING | Идет авторизация | | 3DS_CHECKING | Проходит 3-D Secure | | AUTHORIZED | Авторизован (требует подтверждения) | | CONFIRMED | Подтвержден | | REJECTED | Отклонен | | CANCELED | Отменен | | REFUNDED | Возвращен | | PARTIAL_REFUNDED | Частично возвращен |

Платежи по сохраненным реквизитам (COF-операции)

Библиотека поддерживает все типы COF-операций:

| Тип операции | OperationInitiatorType | Описание | | ---------------------- | ---------------------- | ----------------------------------------- | | CIT COF | '2' | Разовый платеж, инициированный клиентом | | MIT COF Recurring | 'R' | Регулярные платежи без графика (подписки) | | MIT COF Installment | 'I' | Платежи по графику (рассрочка) | | MIT COF Delayed-Charge | 'D' | Отсроченное списание (доначисления) | | MIT COF No-Show | 'N' | Плата за неявку |

Важно: Для использования COF-операций необходимо включить эту возможность на терминале. Обратитесь к персональному менеджеру или на [email protected].

Автоплатежи через СБП

Библиотека поддерживает автоплатежи через Систему быстрых платежей (СБП). Автоплатежи работают только по одностадийной схеме оплаты.

Сценарий использования:

Привязать счет клиента через addAccount
Получить AccountToken в уведомлении о привязке
Создать платеж через initPayment с параметрами Recurrent=Y и DATA={"QR":"true"}
Провести автоплатеж через chargeQr с AccountToken

Подробнее: Документация по автоплатежам

Автор

Разработчик: Eugene Surkov

Telegram: @esurkov1

Безопасность

Все запросы автоматически подписываются
Поддерживается проверка webhook-уведомлений
Чувствительные данные логируются только в debug режиме
Автоматическая генерация токенов
Retry механизм с exponential backoff для надежности

Поддержка

Лицензия

MIT License - см. файл LICENSE

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

T-Bank Payments

Introduction

Установка

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

Проведение платежа

Инициировать платеж

Подтвердить платеж

Подтвердить списание

Прием платежей по карте

Завершение авторизации

Методы для работы с 3DS

Проверить версию 3DS

Пройти этап 3DS Method

Отправить запрос в банк-эмитент для прохождения 3DS

Подтвердить прохождение 3DS v1.0

Подтвердить прохождение 3DS v2.1

Другие способы приема платежей

СБП (Система быстрых платежей)

Сформировать QR

Получить статус QR-кода

Получить список банков-пользователей QR для возврата

Привязать счет к магазину

Получить статус привязки счета к магазину

Получить список счетов, привязанных к магазину

Создать тестовую платежную сессию

Получить список банков-участников СБП для платежа

T-Pay

Определить возможность проведения платежа

Получить ссылку

Получить QR

SberPay

Получить QR

Получить ссылку

Mir Pay

Получить DeepLink

Привязка карты

Методы работы с клиентами

Зарегистрировать клиента

Получить данные клиента

Удалить данные клиента

Методы работы с картами

Инициировать привязку карты к клиенту

Привязать карту

Получить статус привязки карты

Получить список карт клиента

Удалить привязанную карту клиента

Проведение платежа по сохраненным реквизитам

Провести платеж по сохраненным реквизитам

Автоплатеж по QR СБП

Отмена платежа

Отменить платеж

Статус платежа или заказа

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

Получить статус заказа

Справка по операции

Получить справку по операции

Методы работы с чеками

Отправить закрывающий чек в кассу

Получить статус отправки чека

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

Webhook уведомления

Проверка подписи webhook

Тестирование

Тест-кейсы

Тестирование СБП

Коды ошибок

Ошибки 3DS

Ошибки онлайн-кассы

Вспомогательные методы

Создание чека

Конвертация сумм

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

Параметры конструктора

Настройка логирования