@opsregistry/adapter-tbank

Runtime-адаптер для TBank Internet Acquiring.

Пакет мапит операции opsregistry:

• finance.merchantPayment.create -> Init
• finance.merchantPayment.createQr -> GetQr
• finance.merchantPayment.getStatus -> GetState
• finance.merchantPayment.cancel -> Cancel
• finance.fiscalReceipt.createClosing -> /cashbox/SendClosingReceipt
• it.identity.authenticate -> проверка runtime config и описание способа подписи TBank Token

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

import { createAdapter } from '@opsregistry/adapter-tbank';

const tbank = createAdapter({
	terminalKey: process.env.TBANK_TERMINAL_KEY!,
	password: process.env.TBANK_PASSWORD!
});

const auth = await tbank.authenticate({
	requestedAccessMode: 'auto',
	requestedScopes: ['finance.merchantPayment.create']
});

const payment = await tbank.createPayment({
	merchantOrderId: 'order-1001',
	amount: {
		amountMinor: 150000,
		currency: 'RUB'
	},
	description: 'Order order-1001',
	allowedPaymentMethods: ['sbpQr'],
	payType: 'oneStage',
	notificationUrl: 'https://example.com/api/payments/tbank/notify',
	receipt: {
		merchantReceiptId: 'receipt-order-1001',
		merchantOrderId: 'order-1001',
		type: 'sell',
		customer: {
			email: '[email protected]'
		},
		taxationSystem: 'usnIncome',
		items: [
			{
				name: 'Товар',
				price: { amountMinor: 150000, currency: 'RUB' },
				quantity: 1,
				amount: { amountMinor: 150000, currency: 'RUB' },
				vat: 'none',
				paymentMethod: 'fullPayment',
				paymentObject: 'commodity',
				metadata: {}
			}
		],
		amounts: {
			electronic: { amountMinor: 150000, currency: 'RUB' }
		},
		metadata: {}
	},
	metadata: {}
}, { auth });

const qr = await tbank.createPaymentQr({
	providerPaymentId: payment.providerPaymentId,
	format: 'payload',
	metadata: {}
});

const closingReceipt = await tbank.createClosingReceipt({
	providerPaymentId: payment.providerPaymentId,
	merchantReceiptId: 'closing-receipt-order-1001',
	merchantOrderId: 'order-1001',
	type: 'sell',
	customer: {
		email: '[email protected]'
	},
	taxationSystem: 'usnIncome',
	items: [
		{
			name: 'Товар',
			price: { amountMinor: 150000, currency: 'RUB' },
			quantity: 1,
			amount: { amountMinor: 150000, currency: 'RUB' },
			vat: 'none',
			paymentMethod: 'fullPayment',
			paymentObject: 'commodity',
			metadata: {}
		}
	],
	amounts: {
		electronic: { amountMinor: 150000, currency: 'RUB' }
	},
	metadata: {}
});

Важно

• Секреты передаются только в runtime config и не должны попадать в registry.
• Тестовые и production-ключи храните в .env приложения-потребителя, например varm, а не в этом пакете и не в varm-storefront.
• GetState, GetQr и Cancel в этом адаптере требуют providerPaymentId.
• Поле receipt в createPayment мапится в Init.Receipt; поле receipt в cancelPayment мапится в Cancel.Receipt.
• createClosingReceipt мапится в /cashbox/SendClosingReceipt и требует providerPaymentId подтвержденного платежа. Используйте его, когда исходный платеж был фискализирован как fullPrepayment, prepayment или advance, а после передачи товара или услуги нужно закрыть расчет.
• Webhook-и TBank должны обрабатываться в приложении-потребителе отдельно: адаптер пока закрывает исходящие runtime-вызовы.

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

Для sandbox или production runtime нужны:

TBANK_TERMINAL_KEY=""
TBANK_PASSWORD=""
TBANK_API_BASE_URL="https://securepay.tinkoff.ru/v2"

TBank выдает TerminalKey и пароль терминала в личном кабинете интернет-эквайринга. Адаптер использует их для формирования Token и вызова методов Init, GetQr, GetState и Cancel.

Документация TBank Internet Acquiring: https://developer.tbank.ru/eacq/intro