Банк-эквайер с формами

English

@checkout-kit/provider-acquiring — пример адаптера для случая, когда у вас банк-эквайер, чей API принимает поля HTML-формы, использует числа в качестве статусов и старую проверку банком 3-D Secure 1 во фрейме или во всём окне.

• id провайдера: acquiring.
• Чем платит покупатель (инструмент): карта.

Пакет показывает протокол сервера из примеров checkout kit. Используйте его как рабочий шаблон для своей интеграции вместе с поддельным сервером из @checkout-kit/testing/backend. Это не сертифицированный адаптер для какого-либо настоящего банка или платёжной системы. Для Stripe, Adyen и PayPal используйте их собственные пакеты.

Установка из npm

npm install @checkout-kit/core @checkout-kit/runtime-browser @checkout-kit/provider-acquiring

Пакет в npm · Все варианты установки

Настройка

Как установить пакеты, описано в быстром старте.

import { defineProvider } from '@checkout-kit/core'
import type { AcquiringConfig } from '@checkout-kit/provider-acquiring'

const config: AcquiringConfig = {
  baseUrl: '/acquiring',
  userName: 'demo-api',
  password: 'demo',
  acsOrigin: 'https://acs.example.com',
}

const provider = defineProvider({
  id: 'acquiring',
  config: { ...config, credentials: 'include' },
  load: () => import('@checkout-kit/provider-acquiring'),
})
// Pass provider to createCheckout({ providers: [provider], ... }).

• baseUrl — адрес API вашего сервера.
• headers (необязательно) — заголовки вашей сессии или защиты от CSRF. credentials определяет, отправляются ли cookie.
• Секретные ключи платёжного сервиса храните на сервере.
• Браузерный runtime, адрес возврата и адаптер SDK (если нужен) даёт ваше приложение — см. React и работа в браузере.

API сервера

Пути ниже указаны относительно baseUrl. На своём сервере: авторизуйте покупателя, берите цену по planId, проверяйте, что заказ принадлежит этому покупателю, и разрешайте только допустимые смены статуса. Суммы — целые числа в минимальных единицах валюты (например, в копейках или центах).

Метод	Путь	Что делает
POST	/rest/register.do	Форма { planId, orderNumber, currency, amount }. Возвращает { orderId }.
POST	/rest/getOrderStatusExtended.do	Форма { orderId }. Возвращает проверенный числовой статус и активную проверку банком.
POST	/rest/paymentorder.do	Форма { MDORDER, $PAN, $EXPIRY, $CVC }. Возвращает результат или проверку банком.
POST	/rest/finish3ds.do	Форма { MD, PaRes }. Завершает проверку банком.
POST	/rest/reverse.do	Форма { orderId }. Отменяет ещё не завершённый заказ.

Ответы с платежом, заказом или списанием содержат { id, amount, currency, status, error? }. Статусы — значения PaymentStatus из checkout kit. При отказе в error может быть { code?, message }.

Логин и пароль. Все запросы отправляются как данные формы и содержат userName / password. Значения из примера выше работают только с симулятором. В браузерной интеграции baseUrl должен указывать на прокси на вашем сервере. Прокси на стороне сервера подставляет настоящие логин и пароль и проверяет запрос. Никогда не указывайте настоящие данные доступа к банку в этих настройках.

Статусы. В ответах есть errorCode, orderStatus, amount, currency и необязательные поля ошибки от банка. Пока orderStatus === 5, прокси должен ещё возвращать активные MD, acsUrl и paReq этого заказа. С ними адаптер может продолжить проверку банком после перезагрузки страницы и отклонить данные шага от другого заказа. Пример поддерживает коды валют USD/840, EUR/978 и GBP/826.

Результат проверки банком. Демо придумывает PaRes по тестовому ответу. Настоящий банк требует свой подписанный результат и свой протокол; реализуйте этот обмен на своём сервере. Никогда не считайте ответ демо доказательством оплаты.

Повторы и проверка

Прежде чем снова открыть платёж, использовать другой токен или отменить, адаптер читает настоящий заказ с сервера. Успешные, отклонённые и отменённые заказы сохраняют свой результат. Для заказов в обработке статус продолжает проверяться. После потерянного ответа повтор сначала проверяет тот же заказ и только потом отправляет следующее изменение.

Один платёж на заказ. При создании от повторов защищает поле orderNumber в форме. Ваш прокси должен выполнять подтверждение и завершение проверки банком атомарно для каждого заказа. Симулированный банк лишь показывает протокол; это не боевой платёжный шлюз.

Тесты контракта и регрессии для этого пакета:

npm ci
npm test -- packages/provider-acquiring

Запуск и проверка

Запустите npm run dev:mock и npm run dev:bank или откройте демо на сайте. Проверьте успешную оплату, отказ, дополнительный шаг, обработку, повтор и данные от чужого заказа. Это пример протокола, а не интеграция с настоящим банком. Окружение симулятора, восстановление и тестирование объясняют остальное.

Окружение · Восстановление · Каталог