¶ Фрейм оплати
Використовується для прийому платежів торговцями без сертифікату PCIDSS.
¶ Послідовність дій:
- Виконується реєстрація операції методом Реєстрація операції
- callbackurl - окрема сторінка при відкритті якої робиться запит на статус платежу. Метод Статус операції
- У відповіді отримуємо 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(19) | 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(28) | 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
}
}
¶ Статус операції повернення
Отримання статусу операції повернення
<BASE URL>/return-status
¶ Статуси платежу
CREATED - операція створена
PROCESSING - операція відправлена на обробку ПЦ
SUCCESS - операція успішна виконана (фінальний)
FAILED - в процесі виконання операції виникла помилка (фінальний)
¶ Параметри запиту
| Параметр | Тип | Обов'язково | Опис |
| merchantId | string | Y | ідентифікатор торговця |
| terminalId | string | Y | ідентифікатор терміналу |
| merchantTransactionId | string | Y - якщо operationId не передали | ID транзакції в базі торговця |
| operationId | number | Y - якщо merchantTransactionId не передали | ID операції валідації в системі E-COMM |
Важливо! У вхідних параметрах необхідно передавати або operationId або merchantTransactionId. Якщо передати обидва параметри в одному запиті буде помилка!
¶ Приклад запиту with operationId
{
"merchantId": "123456789"
"terminalId": "987456321",
"operationId": 6346582378523
}
¶ Приклад запиту with merchantTransactionId
{
"merchantId": "123456789"
"terminalId": "987456321",
"merchantTransactionId": "bba7c7b1-5cfc-4ba4-ae7b-0273110860223"
}
¶ Параметри відповіді
| Параметр | Тип | Опис |
| status |
string |
Статус результату запиту. Якщо запит виконано успішно, значення "OK" |
| data.purchaseId |
number |
ID оригінальної операції в E-Comm |
| data.merchantTransactionId |
string |
Ідентифікатор операції в базі мерчанта |
| data.pan |
string |
Primary Account Number |
| data.amount |
number |
Сума платежу в копійках |
| data.currency |
number |
ISO 4217 Числовий код валюти платежу |
| data.merchantName |
string |
Найменування мерчанта, отримане від фасілітатора |
| data.status |
string |
Статус операції CREATED - операція створена PROCESSING - операція відправлена на обробку ПЦ SUCCESS - операція успішна виконана (фінальний) FAILED - в процесі виконання операції виникла помилка (фінальний) |
| data.createdUTC |
string |
Дата і час створення операції в UTC |
| data.updatedUTC |
string |
Дата й час останньої зміни операції в UTC |
| data.authorization.rrn |
string |
RRN |
| data.authorization.approvalCode |
string |
Код авторизації |
| data.authorization.stan |
string |
Системний код авторизації |
| data.authorization.tid |
string |
Для карток VISA Transaction Identifier (TID) Для карток Mastercard в якості TID виступає Transaction Link Identifier (TLID) Ідентифікатор авторизації, призначений платіжною системою |
| data.authorization.rtid |
string |
Trace_id для операцій картами Mastercard |
| data.error.code |
number |
Код помилки |
| data.error.message |
string |
Текст помилки |
| data.error.ebppError |
number |
Код відмови процесування |
¶ Зразок відповіді для успішної операції:
{
"status": "OK",
"data": {
"operationId": 100000021675,
"pan": "489537******3478",
"amount": 200,
"currency": 980,
"status": "SUCCESS",
"authorization": {
"rrn": 618203445161,
"approvalCode": "160344",
"stan": "445161",
"tid": "009990701160344"
},
"createdUTC": "2026-07-01 13:03:44",
"updatedUTC": "2026-07-01 13:03:44",
"merchantName": "GAS ONLINE",
"purchaseId": 100000018933,
"merchantTransactionId": "1c66f3be-7886-4534-955c-60714be81b3f"
}
}
¶ Зразок відповіді для неуспішної операції:
{
"status": "OK",
"data": {
"operationId": 100000014277,
"pan": "412364******1110",
"amount": 907,
"currency": 980,
"status": "FAILED",
"authorization": {
"rrn": 614703397526
},
"createdUTC": "2026-05-27 12:16:19",
"updatedUTC": "2026-05-27 12:16:19",
"merchantName": "APARTEL2",
"purchaseId": 100000014186,
"merchantTransactionId": "f9a6ddcc-e667-4602-b0a8-ed5bd6116913",
"error": {
"code": 142,
"message": "Error EBPP. 907",
"details": {
"ebppError": 907
}
}
}
}
¶ Зразок відповіді для операції з помилкою виконання:
{
"status": "FAILED",
"error": {
"code": 500,
"message": "Validation failed: valid operationId or merchantTransactionId one of the fields must be filled in\n"
}
}