Базовые контракты

Контракты Gateway Connect

1. Входящий запрос: POST /pay

Business Service отправляет JSON. Метод передаётся в поле method_name.

{
  "method_name": "pay",
  "params": {
    "customer": {
      "email": "test@test.com",
      "ip": "192.168.1.1",
      "first_name": "Ivan",
      "last_name": "Ivanov",
      "phone": "+12345678"
    },
    "pan": "4111111111111111",
    "cvv": "123",
    "expires": "12/25",
    "card": { "pan": "4111111111111111" },
    "bank_account": {
      "account_number": "IE1234567890123456",
      "bank_code": "BOFI",
      "requisite_type": "card"
    },
    "extra_return_param": "tbank",
    "recurring": true,
    "need_confirmation": true
  },
  "payment": {
    "token": "tok_xxxx",
    "merchant_private_key": "mkey_xxx",
    "gateway_amount": 10000,
    "gateway_currency": "USD",
    "product": "Premium Plan",
    "lead_id": 12345,
    "order_number": "ORD-001",
    "extra_return_param": "user_data"
  },
  "settings": {
    "api_key": "provider_api_token",
    "sign_key": "jwt_secret_key"
  },
  "processing_url": "https://pay.host/...",
  "callback_url": "https://api.business/..."
}

Поля params

Поле	Тип	Обязательное	Описание
customer	object	да	Данные плательщика
customer.email	string	да	Email
customer.ip	string	да	IP-адрес
customer.first_name	string	нет	Имя
customer.last_name	string	нет	Фамилия
customer.phone	string	нет	Телефон
customer.address	string	нет	Адрес
customer.postcode	string	нет	Индекс
customer.city	string	нет	Город
customer.state	string	нет	Регион
customer.country	string	нет	Страна (ISO 3166-1)
customer.birthday	string	нет	Дата рождения
pan	string	нет	Номер карты (H2H)
cvv	string	нет	CVV/CVC (H2H)
expires	string	нет	Срок действия карты MM/YY (H2H)
card	object	нет	Данные карты получателя (Payout)
card.pan	string	нет	Номер карты получателя
card.card_token_from	string	нет	Токен сохранённой карты для восстановления PAN
bank_account	object	нет	Реквизиты банковского счёта
bank_account.account_number	string	нет	Номер счёта
bank_account.bank_code	string	нет	Код банка
bank_account.requisite_type	string	нет	Тип реквизита: card, sbp, account, link, url
extra_return_param	string	нет	Дополнительный параметр, сохраняется в payment.extra_return_param
recurring	boolean	нет	Флаг рекуррентного платежа
need_confirmation	boolean	нет	Флаг двухстадийного платежа

Поля payment

Поле	Тип	Обязательное	Описание
token	string	да	Уникальный токен платежа
merchant_private_key	string	да	Приватный ключ мерчанта (шифруется в коллбеке)
gateway_amount	integer	да	Сумма в копейках (10000 = 100.00)
gateway_currency	string	да	Валюта (ISO 4217)
product	string	нет	Название продукта
lead_id	integer	нет	ID лида
order_number	string	нет	Номер заказа
extra_return_param	string	нет	Дополнительный параметр возврата

Поля settings

См. полный справочник в Настройки и Статусы.

Поля запроса

Поле	Тип	Обязательное	Описание
method_name	string	да	Имя метода: pay, payout, status
processing_url	string	да	URL для возврата пользователя после оплаты
callback_url	string	да	URL для коллбеков от провайдера

2. Ответ Gateway: POST /pay (успех)

HTTP 200. В зависимости от результата — один из трёх форматов ответа.

Успех / ожидание (3DS, Redirect, P2P):

{
  "result": true,
  "status": "pending",
  "gateway_token": "bank_transaction_123",
  "amount": 10000,
  "currency": "USD",
  "redirect_request": {
    "url": "https://3ds.bank.com/challenge",
    "type": "post",
    "params": { "creq": "eyJhb..." }
  },
  "requisites": {
    "card": "461761****3933",
    "holder": "IVAN I.",
    "bank_name": "BankOfBaku",
    "phone": "+77001234567",
    "account": "IE1234567890123456",
    "link": "https://...",
    "deeplink": true,
    "qr_data": "..."
  },
  "recurring_gateway_token": "rec_tok_xxx",
  "gateway_details": {},
  "provider_response_data": {},
  "logs": [...]
}

Поле	Тип	Обязательное	Описание
result	boolean	да	true — успешная обработка
status	string	да	approved, pending, declined
gateway_token	string	да	Идентификатор транзакции у провайдера
amount	integer	нет	Сумма в копейках
currency	string	нет	Валюта
redirect_request	object	нет	Данные для редиректа (см. секцию 3)
requisites	object	нет	Реквизиты для P2P-перевода
recurring_gateway_token	string	нет	Токен для рекуррентных платежей
gateway_details	object	нет	Дополнительные данные шлюза (сохраняются в payment.gateway_details)
provider_response_data	object	нет	Данные провайдера для P2P (wrapped_json_response)
details	string	нет	Описание результата
logs	array	да	Логи взаимодействия (см. секцию 4)

Системная ошибка:

{
  "result": false,
  "error": "Provider returned HTTP 502",
  "logs": [...]
}

3. Структура redirect_request

"redirect_request": {
  "url": "https://3ds.bank.com/challenge",
  "type": "post",
  "params": {
    "creq": "eyJhb..."
  }
}

Поле	Тип	Описание
url	string	URL для перенаправления
type	string	Тип редиректа
params	object	Параметры для передачи

Типы редиректа (type)

Тип	Описание
get	Простой GET-редирект
post	Авто-отправка POST-формы
post_iframes	POST в iframe
get_with_processing	GET-редирект с промежуточной страницей обработки
redirect_html	HTML-редирект

Поддерживаются оба ключа: redirect_request и redirectRequest (camelCase).

4. Формат логов (logs)

Массив объектов, фиксирующий все сетевые взаимодействия с провайдером.

"logs": [
  {
    "request": {
      "url": "https://api.provider.com/v1/pay",
      "body": "{\"amount\": 100, \"currency\": \"USD\"}"
    },
    "status": 200,
    "response": "{\"state\": \"OK\"}",
    "kind": "pay",
    "duration": 0.35
  }
]

Поле	Тип	Описание
request.url	string	URL запроса
request.body	string/object	Тело запроса
status	integer	HTTP-статус ответа провайдера
response	string/object	Тело ответа провайдера
kind	string	Тип операции
duration	float	Длительность запроса в секундах

Значения kind

Значение	Описание
pay	Запрос на оплату
payout	Запрос на выплату
status	Проверка статуса
callback	Обработка коллбека
refund	Возврат
confirm_request	Подтверждение двухстадийного платежа
decline_request	Отклонение двухстадийного платежа
confirm_secure_code	Подтверждение 3DS/OTP
next_payment_step	Следующий шаг оплаты