¶ Фрейм оплати
Використовується для прийому платежів торговцями без сертифікату PCIDSS.
¶ Послідовність дій:
- Виконується реєстрація операції методом Реєстрація операції
- callbacurl - це повинна бути окрема сторінка при відкритті якої робиться запит на статус платежу. Метод Статус операції
- У відповіді отримуємо operationid
- operationid потрібно зберегти для подальшого використання
- Відкриваємо платіжну сторінку {BASE_URL}/?operationId=<operationid з відповіді>
- Після завершення операції платіжна сторінка повертає браузер на сторінку вказану в callbackurl
- Відповідь від запиту на Статус операції потрібно розпарсити та зберегти в реквізитах платежу для подальшої звірки.
¶ Вимоги до передачі даних
Запити надсилаються за допомогою методу POST у форматі JSON. Кодування запитів і відповідей UTF-8. Для передачі запитів використовується API Key отриманий в кабінеті мерчанта.
¶ Заголовок запиту повинен містити такі ідентифікатори:
-H "accept: application/json"
-H Authorization "Bearer": "API Key"
¶ Тіло запиту повинно містити наступні параметри:
- payload - encoded Base64 JSON (структуру наведено нижче)
- signature - base64_encode( sha1(api_key + encoded payload) ), де sha1 - повертає хеш у вигляді бінарного рядку з 20 символів
¶ Приклад запиту
{
"payload": "JVBERi0xLjYNCjBBEFEiE ... lJUVPRg0K"
"signature": "AQAAAAEAACcQAAAAELRJ...2lZX0ypXbrFrKis1DzUUwRCFg=="
}
¶ Приклад відповіді
{
"payload": "JVBERi0xLjYNCjBBEFEiE ... lJUVPRg0K"
}
¶ Потоки даних
- Торговець реєструє заявку на платіж
- Торговець отримує id заявки
- Торговець перенаправляє клієнта на сторінку оплати: {BASE_URL}/operationid= *id заявки на платіж*
- Клієнт обирає метод оплати (APay, GPay, оплата по номеру картки), надає дані для здійснення оплати
- Здійснюється оплата
- Клієнт отримує результат здійснення платежу, при успішній оплаті можливість завантажити квитанцію
- Після фіналізації платежу фрейм оплати перенаправляє клієнта на callbackURL вказаний при реєстрації заявки на платіж
- Торговець виконує запит статусу операції
¶ Реєстрація операції
Реєстрація заявки на платіж
<BASE URL>/registration-operationid
¶ Параметри запиту
payload (encoded base64 json):
| Параметр | Тип | Обов’язково | Опис |
|---|---|---|---|
| merchantid | string | Y | ідентифікатор торговця |
| terminalid | string | Y | ідентифікатор терміналу |
| amount | number | Y | сума в копійках |
| currency | number(3) | Y | валюта операції |
| surcharge | number | N | комісія з боку торговця в копійках |
| description | string | N | коментар до операції або призначення платежу |
| orderid | string | Y | номер операції/замовлення в системі торговця |
| callbackURL | string | N | url на який потрібно здійснити редирект після виконання операції |
| notificationURL | string | N | url методу POST мерчанта на який потрібно передати дані статусу операції |
| expDate | string | N | дата та час до якого необхідно провести оплату по заявці в форматі UTC (2025-05-26T00:00:00Z) important format - yyyy-MM-dd'T'HH:mm:ssX |
¶ Приклад запиту
{
"merchantid": “MERCH1”,
"terminalid": “TERM1”,
"amount": “1000”,
"currency": “980”,
"surcharge": “500”,
"description": “за товар згідно замовлення”,
"orderid": “223344”,
"callbackURL": “https://your_url/callback”
}
¶ Параметри відповіді
| Параметр | Тип | Обов’язково | Опис |
|---|---|---|---|
| operationId | number | Y | ідентифікатор операції |
¶ Приклад відповіді
{
"operationId": 123456,
}
¶ Параметри відповіді з помилкою виконання запиту:
|
Параметр |
Тип |
Опис |
| status | string | Статус результату запиту. Якщо запит виконано з помилкою, значення "FAILED". |
| error.code | number | Код помилки. |
| error.message | string | Текст помилки. |
¶ Приклад відповіді з помилкою:
{
"status": "FAILED",
"error": {
"code": 123,
"message": "3DS authentication of the payer's card is required"
}
}
¶ Статус операції
Отримання статусу заявки на платіж
<BASE URL>/get-purchase-status
¶ Статуси платежу
CREATED - операція створена
3DS_CHALLENGE - операція на етапі 3DS верифікації
3DS_SUCCESS - операція пройшла успішно 3DS верифікацію
PROCESSING - операція відправлена на обробку ПЦ
SUCCESS - операція успішна виконана (фінальний)
FAILED - в процесі виконання операції виникла помилка (фінальний)
¶ Параметри запиту
| Параметр | Тип | Обов’язково | Опис |
|---|---|---|---|
| merchantid | string | Y | ідентифікатор торговця |
| terminalid | string | Y | ідентифікатор терміналу |
| operationid | number | Y | ідентифікатор операції |
¶ Приклад запиту
{
"merchantid": "MERCH1"
"terminalid": "TERM1"
"operationid": 123456
}
¶ Параметри відповіді
| Параметр | Тип | Опис |
| status | string | Статус результату запиту. Якщо запит виконано успішно, значення "OK" |
| data.operationId | number | Id транзакції купівлі, створеної в Сервісі e-com |
| data.pan | string | Номер картки платника в масці |
| data.status | string |
Статус операції
CREATED - операція створена 3DS_CHALLENGE - операція на етапі 3DS верифікації |
| data.amount | number | Сума платежу в копійках |
| data.surcharge | number | Розмір комісії купця в копійках |
| data.currency | number | ISO 4217 Числовий код валюти платежу |
| data.authorization.retrievalData | number | Ідентифікатор транзакції в МПС (RRN) |
| data.authorization.approvalCode | string | Код авторизації |
| data.authorization.stan | string | Системний код авторизації |
| data.createdUTC | string | Дата і час створення операції в UTC |
| data.updatedUTC | string | Дата й час останньої зміни операції в UTC |
¶ Приклад відповіді
{
"status": "OK",
"data":
{
"operationId": 850,
"pan": "4123********0000",
"amount": 99900,
"surcharge": 500,
"currency": 980,
"status": "3DS_CHALLENGE",
"authorization":
{
"retrievalData": 504317967020,
"approvalCode": "045167",
"stan": "967020"
},
"createdUTC": "2025-02-12 15:26:02",
"updatedUTC": "2025-02-12 16:51:22"
}
¶ Параметри відповіді з помилкою виконання запиту:
|
Параметр |
Тип |
Опис |
| status | string | Статус результату запиту. Якщо запит виконано з помилкою, значення "FAILED". |
| error.code | number | Код помилки. |
| error.message | string | Текст помилки. |
¶ Приклад відповіді з помилкою:
{
"status": "FAILED",
"error": {
"code": 123,
"message": "3DS authentication of the payer's card is required"
}
}¶ Повернення операції
Проведення операції повернення
<BASE URL>/purchase-return
- Сума повернення не може перевищувати суму покупки з урахуванням раніше зроблених повернень.
- Якщо з моменту покупки пройшло менше 24 годин буде виконуватись reversal. Більше 24 годин - refund.
¶ Параметри запиту
payload (encoded base64 json):
| Параметр | Тип | Обов'язковість | Опис |
| merchantId | string | Y | |
| terminalId | string | Y | |
| orderId | string | Y | id операції повернення в базі мерчанта |
| purchaseId | number | Y | id батьківської операції покупки |
| аmount | number | Y | сума повернення в копійках |
| currency | number(3) | Y | числовий код валюти повернення по ISO 4217 |
¶ Приклад запиту:
{
"merchantId": "123456789",
"terminalId": "987456321",
"purchaseId": 6346582378523,
"orderId": "361e2ca5-b0ec-40d1-836f-44ea0b20604e",
"amount":1234,
"currency":980
}¶ Приклад відповіді:
{
"status": "OK",
"data": {
"operationId": 123456,
"pan": "1234 **** **** 9876",
"amount": 10000,
"surcharge": 0,
"currency": 980,
"status": "SUCCESS",
"createdUTC": "03.09.2024 09:14:47",
"updatedUTC": "03.09.2024 09:16:08"
}
}¶ Приклад відповіді з помилкою:
HTTP 200
{
"status": "FAILED",
"error": {
"code": 111,
"message": "HTTP error"
"exception": null,
"details": {
"operationId": 19055
}
}