¶ Вимоги до передачі даних
Запити надсилаються за допомогою методу POST у форматі JSON. Кодування запитів і відповідей UTF-8. Для передачі запитів встановлюється SSL сесія з використанням сертифікатів отриманих в кабінеті мерчанту.
¶ Заголовок запиту повинен містити такі ідентифікатори:
- merchantid – ідентифікатор точки продажу
- terminalid - ідентифікатор терміналу
¶ Тіло запиту повинно містити наступні параметри:
- payload - encoded Base64 JSON (структуру наведено нижче)
- signature - SHA-256 з RSA
¶ Приклад запиту
{
"payload": "JVBERi0xLjYNCjBBEFEiE ... lJUVPRg0K"
"signature": "AQAAAAEAACcQAAAAELRJ...2lZX0ypXbrFrKis1DzUUwRCFg=="
}
¶ Тіло відповіді буде містити
- payload - encoded Base64 JSON (структуру наведено нижче)
¶ Приклад відповіді
{
"payload": "JVBERi0xLjYNCjBBEFEiE ... lJUVPRg0K"
}
¶ Потоки повідомлень при оплаті покупки
Оплата може здійснюватися як з 3ds аутентифікацією картки платника, так і без неї. Для виконання платежу без 3ds аутентифікації, заявка на покупку містить параметр No3ds. Для виконання операцій без 3ds, Точка продажу повинна мати відповідний дозвіл від Постачальника.
3ds сервер може проходити аутентифікацію з проханням до Власника Картки підтвердити платіж або без нього (Challenge flow).
Нижче представлені всі три варіанти взаємодії.
¶ No 3DS
- Продавець надсилає до Сервісу запит на оплату покупки з параметром No3ds=true.
- Оплату здійснює сервіс.
- Сервіс повертає результат виконання та дані про оплату в Точку продажу.
¶ Frictionless flow
- Продавець надсилає запит до Сервісу на оплату покупки (no3ds=false або не вказано).
- Сервіс готує і запитує аутентифікацію картки платника з сервера 3DS.
- Сервер 3DS повертає позитивний результат і дані аутентифікації.
- Оплату здійснює сервіс.
- Сервіс повертає результат виконання та дані про оплату в Точку продажу.
¶ Challenge flow
- Продавець надсилає запит до Сервісу на оплату покупки (no3ds=false або не вказано). У запиті вказується URL зворотного дзвінка Точки продажу, на який Власник картки повинен бути перенаправлений після завершення 3ds-челенджу та завершення оплати.
- Сервіс готує і запитує аутентифікацію картки платника з сервера 3DS. У запиті вказується URL зворотного дзвінка сервісу, на який повинен бути відправлений результат 3ds аутентифікації (cRes).
- Сервер 3DS повертає в Сервіс html-сторінку сервера авторизації (ACS) банку-емітента власника картки з даними запиту на підтвердження оплати (cReq).
- Сервіс повертає html сторінку з cReq в Точку продажу.
- Продавець перенаправляє Власника Картки на отриману html сторінку ACS для аутентифікації.
- Власник картки виконує аутентифікацію (OTP, mobile challenge, ...) і підтверджує платіж.
- Сервер ACS генерує cRes і повертає його на html-сторінку Держателю.
- Сторінка html перенаправляє cRes на Сервіс.
- Сервіс перенаправляє Власника картки на html-сторінку, яка очікує оплати.
- Власник картки чекає на здійснення платежу.
- Веб-сервіс, який підтримує HTML-сервіс очікування, періодично опитує службу e-com про статус платежу.
- Отримавши статус завершення платежу, служба очікування перенаправляє Власника картки на URL Точки продажу. Параметр URL передає ідентифікатор операції.
- Сервіс робить запит до сервера 3DS для отримання даних аутентифікації.
- Сервер 3DS повертає результат і дані аутентифікації в Сервіс.
- Сервіс виконує оплату.
- Коли Власник картки перенаправляється на URL Точки продажу, він робить запит до Сервісу для отримання результату оплати.
- Сервіс повертає результат виконання та дані платіжної транзакції в Точку продажу.
¶ Оплата карткою
Оплата покупки з використанням PAN картки. Використовується для виконання оплати карткою та декриптованими даними APay/GPay.
<BASE URL>/ts/purchase
¶ Параметри запиту:
| Параметр | Тип | Обов’язково | Опис |
| merchantTransactionId | string (64) | Y | ID транзакції в базі даних Мерчанта |
| pan | string (16/19) | Y | Номер картки покупця. Тільки цифри, без пробілів. |
| expiryMonth | string (2) | Y | Місяць закінчення терміну дії картки платника. Формат "nn". |
| expiryYear | string (2) | Y | Рік – це закінчення терміну дії картки платника. Формат "nn". |
| cvv | String (3) | Y | CVV2 код картки платника. Формат "nnn". |
| amount | number (10) | Y | Сума оплати вказана в копійках. |
| surcharge | number (10) | N | Розмір комісії торговця (додається до суми) в копійках. |
| currency | number (3) | Y | Цифровий код валюти платежу за стандартом ISO 4217 (для P2P тільки 980). |
| no3ds | boolean | N | Не виконуйте аутентифікацію 3DS. Типове значення: false. |
| callbackUrl | string (256) | Y | URL, на який буде надіслано результат платежу. Його використовують, коли необхідно виконати 3ds-челендж. |
| browser.acceptHeader | string | Y | Вміст HTTP-заголовків accept, відправлених з браузера Власника картки. |
| browser.useragentHeader | string | Y | Вміст HTTP-заголовка user-agent відправляється з браузера Власника картки. |
| browser.language | string () | Y | Мова інтерфейсу браузера власника картки |
| browser.javascriptEnabled | boolean | Y | Підтримка JavaScript у браузері Mapholder |
| browser.colorDepth | number | Y | Глибина кольору екрану браузера. Допустимі значення: 1, 4, 8, 15, 16, 24, 32, 48. |
| browser.screenHeight | number | Y | Висота екрану браузера власника картки в пікселях. |
| browser.screenWidth | number | Y | Ширина екрану браузера власника картки в пікселях. |
| browser.TZ | number | Y | Різниця в часі між часом UTC і місцевим часом браузера власника картки в хвилинах. |
| token.isToken | number (1) | N/Y | ознака того, що операція виконана за токеном (значення = 1 якщо використовуємо детокенізовані дані APay/GPay, обов’язковий при використанні детокенізованих даних.) |
| token.operator | string | N/Y | Ім'я гаманця (apple, google і т.п., обов’язковий при використанні детокенізованих даних) |
| token.authMethod | String | N/Y | Отримане значення з гаманця може набувати такого значення: '3DSecure', 'CRYPTOGRAM_3DS', 'PAN_ONLY' (обов’язковий при використанні детокенізованих даних) |
| token.сryptogram | string | N/Y | Значення, отримане з гаманця, для Google-подібних гаманців залежить від значення поля 'authMethod'. Для значення поля 'authMethod' = 'PAN_ONLY', значення 'tokenCryptogram' = null (обов’язковий при використанні детокенізованих даних) |
| token.eciIndicator | number (2) | N/Y | Значення, отримане з гаманця, залежить від значення поля 'authMethod'. У деяких випадках може набувати значення null (обов’язковий при використанні детокенізованих даних) |
¶ Приклад запиту (оплата карткою):
{
"merchantTransactionId": 98765,
"cardHolder": "Ivanov Ivan",
"pan": "1111222233334444",
"expiryMonth": "05",
"expiryYear": "29",
"cvv": "038",
"amount": 12345,
"surcharge": 123,
"currency": 980,
"callbackUrl": "https://merchant.com/purchase_result",
"browser": {
"acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"useragentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Firefox/47.0",
"javascriptEnabled": true,
"language": "ua",
"colorDepth": 48,
"screenHeight": 1080,
"screenWidth": 1920,
"TZ": 120
}
}
¶ Приклад запиту (оплата декриптованим токеном apple/google):
{
"merchantTransactionId": 98765,
"cardHolder": "Ivanov Ivan",
"pan": "1111222233334444",
"expiryMonth": "05",
"expiryYear": "29",
"cvv": "038",
"amount": 12345,
"surcharge": 123,
"currency": 980,
"callbackUrl": "https://merchant.com/purchase_result",
"browser": {
"acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"useragentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Firefox/47.0",
"javascriptEnabled": true,
"language": "ua",
"colorDepth": 48,
"screenHeight": 1080,
"screenWidth": 1920,
"TZ": 120
}
"token": {
"isToken": 1,
"operator": "google",
"authMethod": "CRYPTOGRAM_3DS",
"cryptogram": "ALnt+yWSJdXBACMLLWMNGgADFA==",
"eciIndicator": 05
}
}
¶ Параметри відповіді без 3ds-challenge:
| Параметр | Тип | Опис |
| 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.rrn | number | Ідентифікатор транзакції в МПС (RRN) |
| data.authorization.approvalCode | string | Код авторизації |
| data.authorization.stan | string | Системний код авторизації |
| data.createdUTC | string | Дата і час створення операції в UTC |
| data.updatedUTC | string | Дата й час останньої зміни операції в UTC |
¶ Приклад відповіді без 3ds-челенджу:
{
"status": "OK",
"data": {
"operationId": 850,
"pan": "4123********0000",
"amount": 99900,
"surcharge": 500,
"currency": 980,
"status": "3DS_CHALLENGE",
"authorization": {
"rrn": 504317967020,
"approvalCode": "045167",
"stan": "967020"
},
"createdUTC": "2025-02-12 15:26:02",
"updatedUTC": "2025-02-12 16:51:22"
}
}
¶ Параметри відповіді з 3ds-challenge:
| Параметр | Тип | Опис |
| status | string | Статус результату запиту. Якщо запит виконано успішно, значення OK. |
| data.operationId | number | Ідентифікатор транзакції покупки, створений в сервісі e-comm. |
| data.creq | object | Зміст челенджу |
¶ Приклад відповіді з 3ds-challenge:
{
"status": "OK",
"data": {
"operationid": 123456,
"creq": {
"threeDSServerTransID": "f3ab2a21-c5db-42da-b30a-271b24ea15a9",
"acsTransID": "c83afa81-faba-432e-8c9e-2eb8ee11a716",
"dsTransID": "1b0256de-ab33-4265-8c1f-dc1925fc57b8",
"transStatus": "C",
"eci": "00",
"xid": "VGnMqa+1jNBTSnCnoh3K8PuiVZQ=",
"protocolVersion": "2.1.0",
"authenticationType": "02",
"acsChallengeMandated": "Y",
"acsURL": "https://acs.com/v2.1.0/acs/",
"html": "<html><form action=https://acs.com/v2.1.0/acs/ method=post>\n<inputname=creq\nvalue=eyJhY3N..."
}
}
}
¶ Параметри відповіді з помилкою виконання запиту:
|
Параметр |
Тип |
Опис |
| status | string | Статус результату запиту. Якщо запит виконано з помилкою, значення "FAILED". |
| error.code | number | Код помилки. |
| error.message | string | Текст помилки. |
¶ Приклад відповіді з помилкою:
{
"status": "FAILED",
"error": {
"code": 123,
"message": "3DS authentication of the payer's card is required"
}
}
¶ Оплата токеном GPay
Декриптація токену виконується на стороні сервісу E-com
Для запиту токену використовувати:
gateway: amofintech
gatewayMerchantId: The unique identifier of the merchant, which is provided to each partner when connecting to AMOFINTECH payment gateway.
Підтримуються платіжні системи VISA та MASTERCARD
<BASE URL>/ts/googlePurchase
¶ Параметри запиту:
| Параметр | Тип | Опис |
| merchantTransactionId | string (64) | ID транзакції в базі даних Мерчанта |
| amount | number (10) | Сума оплати вказана в копійках. |
| surcharge | number (10) | Розмір комісії торговця (додається до суми) в копійках. |
| currency | number (3) | Цифровий код валюти платежу за стандартом ISO 4217 (для P2P тільки 980). |
| no3ds | boolean | Не виконуйте аутентифікацію 3DS. Типове значення: false. |
| callbackUrl | string (256) | URL, на який буде надіслано результат платежу. Його використовують, коли необхідно виконати 3ds-челендж. |
| browser.acceptHeader | string | Вміст HTTP-заголовків accept, відправлених з браузера Власника картки. |
| browser.useragentHeader | string | Вміст HTTP-заголовка user-agent відправляється з браузера Власника картки. |
| browser.language | string () | Мова інтерфейсу браузера власника картки |
| browser.javascriptEnabled | boolean | Підтримка JavaScript у браузері Mapholder |
| browser.colorDepth | number | Глибина кольору екрану браузера. Допустимі значення: 1, 4, 8, 15, 16, 24, 32, 48. |
| browser.screenHeight | number | Висота екрану браузера власника картки в пікселях. |
| browser.screenWidth | number | Ширина екрану браузера власника картки в пікселях. |
| browser.TZ | number | Різниця в часі між часом UTC і місцевим часом браузера власника картки в хвилинах. |
| googletoken. protocolVersion | string | |
| googletoken. signature | string | |
| googletoken. intermediateSigningKey. signedKey | String | |
| googletoken. intermediateSigningKey. signatures | string | |
| googletoken.signedMessage | number (2) |
¶ Приклад запиту:
{
"merchantTransactionId": 125461,
"amount": 505,
"surcharge": 50,
"currency": 980,
"callbackUrl": "https://merchant.com/api/callback",
"browser": {
"acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"useragentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Firefox/47.0",
"javascriptEnabled": true,
"language": "ua",
"colorDepth": 48,
"screenHeight": 1080,
"screenWidth": 1920,
"TZ": 120
},
"googletoken":{
"signature":"****",
"intermediateSigningKey":{
"signedKey":"{\"******\"}",
"signatures":["*****"]
},
"protocolVersion":"ECv2",
"signedMessage":"***"
}
}
¶ Параметри відповіді:
аналогічно з методом purchase
¶ Оплата токеном APay
Декриптація токену виконується на стороні сервісу E-com
Для запиту токену використовувати:
gateway: amofintech
merchantIdentifier: *реєструється окремо для кожного торговця *
Підтримуються платіжні системи VISA та MASTERCARD
Для запиту токену у випадку оплати на Web ресурсах необхідно надати csr для випуску Apple Pay Merchant Identity Certificate. Офіційна документація Apple для створення csr: https://developer.apple.com/help/account/certificates/create-a-certificate-signing-request
Також необхідно пройти верифікацію домену з якого будуть виконуватися запити токену.
<BASE URL>/ts/applePurchase
¶ Параметри запиту:
| Параметр | Тип | Опис |
| merchantTransactionId | string (64) | ID транзакції в базі даних Мерчанта |
| amount | number (10) | Сума оплати вказана в копійках. |
| surcharge | number (10) | Розмір комісії торговця (додається до суми) в копійках. |
| currency | number (3) | Цифровий код валюти платежу за стандартом ISO 4217 (для P2P тільки 980). |
| no3ds | boolean | Не виконуйте аутентифікацію 3DS. Типове значення: false. |
| callbackUrl | string (256) | URL, на який буде надіслано результат платежу. Його використовують, коли необхідно виконати 3ds-челендж. |
| browser.acceptHeader | string | Вміст HTTP-заголовків accept, відправлених з браузера Власника картки. |
| browser.useragentHeader | string | Вміст HTTP-заголовка user-agent відправляється з браузера Власника картки. |
| browser.language | string () | Мова інтерфейсу браузера власника картки |
| browser.javascriptEnabled | boolean | Підтримка JavaScript у браузері Mapholder |
| browser.colorDepth | number | Глибина кольору екрану браузера. Допустимі значення: 1, 4, 8, 15, 16, 24, 32, 48. |
| browser.screenHeight | number | Висота екрану браузера власника картки в пікселях. |
| browser.screenWidth | number | Ширина екрану браузера власника картки в пікселях. |
| browser.TZ | number | Різниця в часі між часом UTC і місцевим часом браузера власника картки в хвилинах. |
| appletoken.data | string | |
| appletoken.signature | string | |
| appletoken.header.publicKeyHash | String | |
| appletoken.header.ephemeralPublicKey | string | |
| appletoken.header.transactionId | string | |
| appletoken.version | string |
¶ Приклад запиту:
{
"merchantTransactionId": 125498,
"amount": 505,
"surcharge": 50,
"currency": 980,
"callbackUrl": "https://merchant.com/api/callback",
"browser": {
"acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"useragentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Firefox/47.0",
"javascriptEnabled": true,
"language": "ua",
"colorDepth": 48,
"screenHeight": 1080,
"screenWidth": 1920,
"TZ": 120
},
"appletoken":{
"data":"***",
"signature":"****",
"header":{
"publicKeyHash":"****",
"ephemeralPublicKey":"***",
"transactionId":"****"
},
"version":"EC_v1"
},
}
¶ Параметри відповіді:
аналогічно з методом purchase
¶ Статус операції
<BASE URL>/ts/purchase-status
¶ Параметри запиту:
| Параметр | Тип |
Обов'язковою |
Опис |
| operationId |
number |
Y |
ID операції покупки в сервісі e-comm. |
¶ Приклад запиту:
{
"operationId": 123456
}
¶ Параметри відповіді:
ідентично відповіді без 3ds-challenge
¶ Операція повернення
Повернення коштів за здійснену оплату
<BASE URL>/ts/purchase-return
¶ Параметри запиту:
|
Параметр |
Тип |
Обов'язковою |
Опис |
| merchantTransactionId | string (64) |
Y |
ID транзакції в базі даних Мерчанта |
| purchaseId | number |
Y |
ID первинної операції покупки у сервісі e-comm |
| pan | string (16,19) |
N |
Номер картки покупця. Тільки цифри, без пробілів. необов'язковий якщо немає параметрів expiryMonth, expiryYear |
| expiryMonth | string (2) |
Y/ N (if pan empty) |
Місяць закінчення терміну дії картки платника. Формат "nn". |
| expiryYear | string (2) |
Y/ N (if pan empty) |
Рік – це закінчення терміну дії картки платника. Формат "nn". |
| amount | number (10) |
Y |
Сума повернення в копійках. |
| currency | number (3) |
Y |
Цифровий код валюти платежу за стандартом ISO 4217 (для P2P тільки 980). |
| isToken | number(1) |
N |
Ідентифікатор token PAN. Значення по замовченню = 0. Якщо операція виконується по token PAN передавати значення = 1
|
| authMethod | string |
N / Y if isToken = 1 |
Значення, яке отримали від гаманця. Можливі варіанти: '3DSecure', 'CRYPTOGRAM_3DS', 'PAN_ONLY' |
| cryptogram | string |
N / Y if isToken = 1 |
Значення, яке отримали від гаманця. Залежить від значення параметру authMethod. Якщо ‘authMethod’= 'PAN_ONLY', значення ‘cryptogram’ = null |
| operator | string |
N / Y if isToken = 1 |
Назва гаманця (apple, google) |
¶ Обмеження:
- Якщо з моменту покупки пройшло менше 24 годин, карта, на яку здійснюється повернення коштів, не може відрізнятися від карти, яка використовувалася для оплати покупки.
- Валюта повернення коштів не може відрізнятися від валюти покупки.
- Сума повернення не може перевищувати суму покупки з урахуванням раніше зроблених повернень.
- Якщо повернення виконується по purchaseId без передачі даних картки, параметри pan, expiryMonth, expiryYear, isToken, authMethod, cryptogram, operator не передаються в запиті.
- Якщо повернення виконується на картку, параметри pan, expiryMonth, expiryYear обов'язкові, параметри isToken, authMethod, cryptogram, operator не передаються в запиті.
- Якщо повернення виконується з використанням token PAN, обов'язково вказувати isToken = 1, параметри pan, expiryMonth, expiryYear, authMethod, cryptogram, operator обов'язкові!
¶ Приклад запиту:
{
"merchantTransactionId": 98765,
"purchaseId": 12345,
"pan": "1122334455228899",
"expiryMonth": "05",
"expiryYear": "29",
"amount": 10000,
"currency": 980
}
¶ Параметри відповіді:
ідентично відповіді без 3ds-challenge
¶ Статус операції повернення
<BASE URL>/ts/return-status
¶ Параметри запиту:
| Параметр | Тип | Обов'язковість | Опис |
| operationId | number | Y | id операції повернення |
¶ Приклад запиту:
{
"operationId": 12299
}¶ Приклад відповіді:
{
"status": "OK",
"data": {
"operationId": 12299,
"purchaseId": 12175,
"merchantTransactionId": "83012d7a-613d-4d68-968f-6f8a354ae620",
"pan": "412364******1110",
"amount": 100,
"currency": 980,
"status": "SUCCESS",
"authorization": {
"rrn": 517509799443,
"approvalCode": 093411,
"stan": 799443
},
"createdUTC": "24.06.2025 6:34:12",
"updatedUTC": "24.06.2025 6:34:12"
}
}