API callback - это API POST метод, который должен быть реализован в системе клиента, его адрес должен передаваться при любом депозите и выплате в систему биллинга, по этому адресу будут приходить обновления для ордера в системе биллинга, которая в свою очередь обрабатывает изменения ордера платежной системы.
Метод запроса: POST
Заголовки запроса:
X-Client-Id: (обязательно). Идентификатор вашего приложения. Нужен для проверки подписи.X-Signature: (обязательно). Подпись запроса в формате HMAC-SHA256 (hex). Система биллинга формирует её секретным ключом вашего приложения. Проверьте её по алгоритму, описанному на странице «Подпись».X-Timestamp: (обязательно). Время формирования запроса — UTC Unix-время в секундах.X-Nonce: (обязательно). Уникальный идентификатор запроса (UUID v4).Content-Type: (обязательно) Тип содержимого запроса, должно быть application/json.Проверка подписи
Подпись считается по схеме v2 (см. «Подпись») над данными именно этого callback-запроса:
METHOD = POST;PATH = путь вашего callback-URL (того, что вы передали при создании ордера);CANONICAL_QUERY = query вашего callback-URL (обычно пусто);CLIENT_ID, TIMESTAMP, NONCE — из заголовков X-Client-Id, X-Timestamp, X-Nonce.Пересоберите каноническую строку, посчитайте HMAC-SHA256 секретным ключом вашего приложения и сверьте результат с заголовком X-Signature.
Структура тела запроса от системы биллинга:
Тело запроса в формате JSON и имеет следующую структуру:
{
"id": 753,
"confirmationType": "3DS_PAYMENT_PAGE",
"status": "IN_PROGRESS",
"amount": 1000,
"currency": "RUB",
"paymentDetails": {
"accountNumber": "40817810099910004312",
"bankName": "Some Bank",
"recipientName": "John Doe"
},
"error": "Transaction was declined because of some reason",
"merchantOrderId": "347995",
"merchantClientId": "client-123",
"redirectUrl": "https://payment.page/deposit/session-id",
"sessionId": "some-id",
"bonusCode": "bonus"
}
| Наименование | Тип | Обязательность | Описание |
|---|---|---|---|
id |
integer | Да | ID ордера, созданного для платежа на стороне системы биллинга. |
confirmationType |
string | Нет | Тип подтверждения платежа. Может иметь пустое значене или "3DS_PAYMENT_PAGE" для 3DS смс подтверждения карточного депозита BankCard H2H. |
status |
string | Да | Текущий статус ордера системы биллинга. Возможные значения:
|
amount |
float | Да | Сумма платежа. |
currency |
string | Да | Валюта платежа. 3-х значный буквенный код валюты платежа по ISO 4217. |
error |
string | Нет | Ошибка от ПС. |
merchantOrderId |
string | Да | ID ордера клиента. |
redirectUrl |
string | Нет | URL ссылка, для перехода пользователя выполняющего оплату на сторонний терминал ПС, либо на 3DS подтверждение. |
sessionId |
string | Нет | Идентификатор сессии в терминале |
bonusCode |
string | Нет | Бонус-код, указанный при создании ордера |
1. Успешный ответ (статус 200)
Тело ответа отсутствует.
2. Ошибка доступа (статус 403)
Тело ответа отсутствует.
Если подпись X-Signature некорректна или отсутствует, верните ответ со статусом 403 Forbidden.
3. Ошибка данных запроса (статус 422)
Если одно из полей не пройдет проверку:
, то необходимо вернуть ответ на запрос со статусом 422 и следующей структурой:
{
"field": "Field_name",
"error": "Description error"
}