Обов'язково
Версія апі, яку ви використовуєте передається в заголовку з назвою Api-Version. Поточну версію, а також зміни в попередніх можна подивитись в Історії змін
Api-Version: 1.33
Для взаємодії слід отримати наступні значенння:
URL адреса для запитів PaymentCreate - https://tokly.ipay.ua/api302
Формат передачі - XML методом POST у полі data
приклад налаштування для CURL: CURLOPT_POSTFIELDS, ['data' =>
$xml]
CONSOLE CURL: curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded' -i 'https://tokly.ipay.ua/api302' --data 'data= ...
URL адреса для запитів CreateToken - https://tokly.ipay.ua/api
Формат передачі - JSON методом POST
Кодування у UTF-8
$salt = sha1(microtime(true));2. Підпис: Згенерувати хеш-код на основі ключа для підпису та солі, використовуючи метод HMAC і алгоритм хешування SHA-512
$sign = hash_hmac('sha512', $salt, $sign_key);
Кодування карткових данних виконується за допомогою OpenSSL та ключа, закодовані картданні використовуються у для опціонального поля request.body.cdata у запросі: CreateToken
Ключ для кодування надає менеджер iPay
Реалізація кодування:
алгоритм: aes-256-gcm
$cipher = "aes-256-gcm";
вектор ініціалізації (iv): хєш sha3-512 ключа для кодування картданних
$iv = hash('sha3-512', $key);
карткові данні повинні бути представлені у форматі JSON в якому містится ключ та значення
$raw_data = {"pan":"1234567890123456"}
приклад кодування на php
$encoded_pan = openssl_encrypt($data_to_encode, $cipher, $key, $options = 0, $iv, $tag);
при кодуванні формується змінна $tag в яку передається тєг аутентифікації, його потрібно закодувати в base64
$tag = base64_encode($tag);
закодований пан треба сканкатенувати через роздільник крапку (.) з тэгом аутентифікації
$encoded_pan.$tag;
Результатом кодування має бути строка у виді:
Приклад реалізації метода кодування на PHP:omhlJHD00QZk32WstDHpAOGHV+bkud62nXI=.cyDAn2Q4QA2L++sICPciVw==
encrypted_pan = $this->encryptData('{"pan":"1234567890123456"}', '11122233344455566677778889990000'); private function encryptData($raw_data = NULL, $key = NULL){ //$raw_data = {"pan":"1234567890123456"} if(empty($raw_data) || empty($key)) return; $cipher = "aes-256-gcm"; if(is_array($raw_data)) $raw_data = json_encode($raw_data); $data_to_encode = $raw_data; $iv = hash('sha3-512', $key); $ciphertext = openssl_encrypt($data_to_encode, $cipher, $key, $options = 0, $iv, $tag); $tag = base64_encode($tag); return $ciphertext.'.'.$tag; } //https://www.php.net/manual/ru/function.openssl-encrypt.php //openssl-encrypt in this mode, not only does the AES block cipher get applied, //but an authentication tag gets calculated as well. It is an array of bytes //that represents a MAC (Message Authentication Code) that can be used to verify //the integrity of the data and wen decrypting. That same tag needs to be provided //to do that verification. See the Wikipedia page about Galois/Counter Mode for more details.
Sandbox - тестове середовище, з допомогою якого можна виконати:
тестування запитів, тестування web інтерфейсу, провести тестову оплату, виконати тестове скасування
Посилання для подання запиту на формування платежу виконується як звичайно , але з додатковим параметром request.environment: "sandbox" (payment.environment = sandbox для PaymentCreate)
Для тестування необхідно використовувати наведені нижче карти, з будь-якою датою та CVV
Для web тестування запитів CreateToken, PaymentCreate Debiting необхідно використовувати наведені нижче карти, з будь-якою датою та CVV
Карти для яких завжди буде успіх, незалежно від суми:
3333333333333331
3333333333332705
3333333333333000
3333333333331640
3333333333334909
3333333333333703
3333333333332820
5375913862726080
Карти для яких успіх буде при сумі до 100 грн, платежі з більшою сумою будуть давати неуспіх:
3333333333333430
3333333333331509
5375912476960515
5117962099480048
4005520000000129
4164978855760477
Карти, для яких може бути Предавторизація. Лише за умови відповідного налаштування В нашій системі:
3333333333479407
3333333333334503
5117963095204135
4341500505113562
Для неуспіху, незалежно від суми:
3333333333333349
3333333333336409
3333333333339205
3333333333338710
3333333333337605
3333333333337340
3333333333339403
3333333333337720
3333333333335120
3333333333335930
4280596505234682
5218572540397762
Для предавторизації, незалежно від суми:
3333333333333356
Для успіху - 3333333333333331
Для неуспіху(з випадковим кодом помилки) - 3333333333333349
Для помилки "insufficient_balance" - 3333333333334552
Будь-який інший валідний номер карти призведе до помилки "invalid sandbox pan"
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
Після виконання запиту у відповідь повертається URL, по якому клієнт робить "валідацію" карти
Так-як "валідація" карти здійснюється безпосередньої участі мерчанта, на стороні tokly.ipay.ua, то мерчанту по
завершенню
приходить нотифікація з токеном карти
Запит може містити закодовані картданні, у такому випадку сторінка "валідаціі" карти буде містити вже заповнені поля
Якщо request.body.info містить user_id, то значення user_id буде зв'язано з токеном.
За цим значенням можно виконати запит GetTokenList і отримати список зв'язаних
токенів
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | integer | Назва запиту |
| request.body | element | Тіло запиту, може бути пустим так-як містить опціональні поля |
| request.lang | string | Мова яку буде відображено на WEB сторінках (ua - українська, ru - російська, en - англійська) |
| Опціональні поля | ||
| request.body.cdata | string | Закодовані картданні |
| request.body.url_good | string | Абсолютне посилання до сторінки успіху мерчанта, використання ip буде призводити до помилки |
| request.body.url_bad | string | Абсолютне посилання до сторінки неуспіху мерчанта, використання ip буде призводити до помилки |
| request.body.info | json | Інформація до платежу, надається мерчантом. Повертається мерчанту в нотифікації |
| request.body.info.user_id | string | Ідентифікатор користувача, по якому пізніше можна отримати список токенів за допомогою методу GetTokenList |
| Додаткові поля info | ||
| request.body.info.cvd | element | Елемент Card Verification Data |
| request.body.info.cvd.tax_id | string | ИНН |
| request.body.info.cvd.firstname | string | Имя |
| request.body.info.cvd.lastname | string | Фамилия |
| request.body.info.cvd.middlename | string | Отчество |
| request.body.info.cvd.phone_number | string | Номер телефону у форматі 380YYXXXXXXX |
| request.body.info.aml | string | Дані про учасників платежу для фінансового моніторингу. Можуть дублюватись з даними в request.body.info.cvd |
| request.body.info.aml.sender_firstname | string | Ім'я відправника |
| request.body.info.aml.sender_middlename | string | По-батькові відправника |
| request.body.info.aml.sender_lastname | string | Прізвище відправника |
| request.body.info.aml.sender_identification_number | string | ІПН (Індивідуальний податковий номер) / Код ЄДРПОУ (Єдиного державного реєстру підприємств та організацій України) відправника |
| request.body.info.aml.sender_document | string | Номер документа відправника |
| request.body.info.aml.sender_address | string | Адреса відправника |
| request.body.info.aml.sender_account_number | string | Розрахунковий рахунок відправника |
| request.body.info.additional_tokens.mcts_vts | bool | Тип токену. Якщо встановлено, то разом з токеном tokly створиться токен mcts/vts. |
| request.body.info.allowed_card_types | array | Дозволені типи карт для операції (можливі значення: mastercard, visa) |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"a12a4d5eb7da121bc04d360a5c11fd7b..." }, "action":"CreateToken", "body":{ "info":{ "order_id":112233, "ext_id":12345, "user_id":54321, "cvd":{ "tax_id":123456789, "firstname":"name", "lastname":"surname", "middlename":"patronymic", "phone_number":380501234567 } } }, "lang":"ru" } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt_id | integer | ID платежу в системі iPay |
| response.url | string | URL по якому треба перейти для здійснення "валідації" |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response":{ "pmt_id":44482723, "url":"https:\/\/tokly.ipay.ua\/08196505afe03bab0ff4907b7e0fc8005c6391c8", "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2" } }
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
Після виконання запиту у відповідь повертається URL, по якому клієнт робить "валідацію" карти за технолонією 3D Secure
Так як "валідація" карти здійснюється за безпосередньої участі мерчанта, на стороні tokly.ipay.ua, то мерчанту по
завершенню
приходить нотифікація з токеном карти
Запрос містить обов'язкове поле verify_type яке набуває значень no_amount або with_amount
- якщо буде передано значення no_amount відбудеться 3DS перевірка карти на сумму 0 грн,
- якщо буде передано значення with_amount буде виконана перевірка карти з списанням з картки 1 грн, та
поверненням 1 грн на карту.
В результаті якщо 3DS перевірка була успішною, формується токен карти, та відправляється у нотифікації
У разі неуспішної 3DS перевірки, токен не буде сформовано і він не буде міститися у нотифікації.
Запит може містити закодовані картданні, у такому випадку сторінка "валідаціі" карти буде містити вже заповнені поля карти
Якщо request.body.info містить user_id, то значення user_id буде зв'язано з токеном.
За цим значенням можно виконати запит GetTokenList і отримати список зв'язаних
токенів
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | integer | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.verify_type | string | Варіант валідації: no_amount - 3DS на 0 грн. with_amount - 3DS на 1 грн. з поверненням на карту |
| request.lang | string | Мова яку буде відображено на WEB сторінках (ua - українська, ru - російська, en - англійська) |
| Опціональні поля | ||
| request.body.cdata | string | Закодовані картданні |
| request.body.url_good | string | Абсолютне посилання до сторінки успіху мерчанта, використання ip буде призводити до помилки |
| request.body.url_bad | string | Абсолютне посилання до сторінки неуспіху мерчанта, використання ip буде призводити до помилки |
| request.body.info | json | Інформація до платежу, надається мерчантом. Повертається мерчанту в нотифікації |
| request.body.info | string | Ідентифікатор користувача, по якому пізніше можна отримати список токенів за допомогою методу GetTokenList |
| Додаткові поля info | ||
| request.body.info.cvd | element | Елемент Card Verification Data |
| request.body.info.cvd.tax_id | string | ИНН |
| request.body.info.cvd.firstname | string | Ім'я |
| request.body.info.cvd.lastname | string | Прізвище |
| request.body.info.cvd.middlename | string | Отчество |
| request.body.info.cvd.phone_number | string | Номер телефону 380YYXXXXXXX |
| request.body.info.aml | string | Дані про учасників платежу для фінансового моніторингу. Можуть дублюватись з даними в request.body.info.cvd |
| request.body.info.aml.sender_firstname | string | Ім'я відправника |
| request.body.info.aml.sender_middlename | string | По-батькові відправника |
| request.body.info.aml.sender_lastname | string | Прізвище відправника |
| request.body.info.aml.sender_identification_number | string | ІПН (Індивідуальний податковий номер) / Код ЄДРПОУ (Єдиного державного реєстру підприємств та організацій України) відправника |
| request.body.info.aml.sender_document | string | Номер документа відправника |
| request.body.info.aml.sender_address | string | Адреса відправника |
| request.body.info.aml.sender_account_number | string | Розрахунковий рахунок відправника |
| request.body.info.additional_tokens.mcts_vts | bool | Тип токену. Якщо встановлено, то разом з токеном tokly створиться токен mcts/vts. |
| request.body.info.allowed_card_types | array | Дозволені типи карт для операції (можливі значення: mastercard, visa) |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"a12a4d5eb7da121bc04d360a5c11fd7b..." }, "action":"CreateToken3DS", "body":{ "cdata":"omhlJHD00QZk32WstDHpAOGHV+bkud62nXI=.cyDAn2Q4QA2L++sICPciVw==", "verify_type":"no_amount", "info":{ "order_id":112233, "ext_id":12345, "user_id":54321, "cvd":{ "tax_id":123456789, "firstname":"name", "lastname":"surname", "middlename":"patronymic", "phone_number":380501234567 } } }, "lang":"ru" } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt_id | integer | ID платежу в системі iPay |
| response.url | string | URL по якому треба перейти для здійснення "валідації" |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response":{ "pmt_id":44482723, "url":"https:\/\/tokly.ipay.ua\/08196505afe03bab0ff4907b7e0fc8005c6391c8", "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2" } }
Після створення платежу у відповідь повертається URL, по якому клієнт робить оплату послуги/товару
Так-як оплата клієнтом здійснюється безпосередньої участі мерчанта, на стороні tokly.ipay.ua, то мерчанту по
завершенню
оплати приходить нотифікація
Якщо потрібно передавати карткові дінні, то треба заповнювати секцію card, яка повинна містити одночасно
тільки:
token: токен карткових данних
або
cdata: закодований пан карти
У разі переданої секції card.token користувач вводить лише cvv, у разі card.cdata користувач вводить строк дії та cvv
Якщо секція не буде заповнена, повні карткові данні користувач буде вводити самостійно
У випадку успішного платежу, може бути сформована нотифікація яка буде містити token
За додатково узгодженими умовами з мерчантом для клієнта може бути відображена інформация з полів payment.transactions.transaction.info
Якщо payment.transactions.transaction.info містить user_id, то значення user_id буде зв'язано з токеном.
За цим значенням можно виконати запит GetTokenList і отримати список зв'язаних
токенів
Якщо мерчант працює з предавторизацією, payment.status = 3 у відповіді на запрос, або у нотифікації,
то для успішного завершення платежа потрібно виконувати запит Completion (Завершити
платіж)
| Поле | Тип | Опис |
|---|---|---|
| payment | element | Початковий елемент |
| payment.auth | element | Елемент аутентифікації |
| payment.auth.mch_id | integer | ID мерчанта |
| payment.auth.salt | string | Сіль підпису |
| payment.auth.sign | string | Підпис запиту |
| payment.urls | element | Елемент посилань |
| payment.urls.good | string | Посилання до сторінки успіху мерчанта |
| payment.urls.bad | string | Посилання до сторінки неуспіху мерчанта |
| payment.card | element | Елемент карткових даних |
| payment.transactions | element | Елемент транзакцій |
| payment.transactions.transaction | element | Елемент транзакції |
| payment.transactions.transaction.amount | integer | Сума у копійках |
| payment.transactions.transaction.currency | string | Валюта |
| payment.transactions.transaction.desc | string | Опис платежу |
| payment.transactions.transaction.info | json object | Інформація до платежу, надається мерчантом при створенні |
| payment.lifetime | float | Термін можливості зробити оплату, вимірюється у годинах(3600 секунд). Може бути дробовим. У випадку значення 0.1, термін життя посилання 6 хвилин(360 секунд) |
| payment.lang | string | Мова яку буде відображено на WEB сторінках (ua - українська, ru - російська, en - англійська) |
| Опціональні поля | ||
| payment.environment | string | Середовище в якому буде проходити платіж (sandbox - тестове середовище, в будь-якому іншому випадку буде прод середовище) |
| payment.ext_id | string | Внутрішній айді платежу в системі мерчанта. Його можна використовувати для отримання статусу платежу в GetPaymentStatus |
| payment.transactions.transaction.smch_id | integer | Юридична особа, на користь якої здіюйснюється операція |
| payment.card.token_type | string | Тип токену. Можливі варіанти: tokly, mcts, vts. За замовчуванням: tokly |
| payment.card.token | string | Токен карти |
| payment.card.cdata | string | Закодований пан карти |
| Додаткові поля info | ||
| payment.transactions.transaction.info.cvd | element | Елемент Card Verification Data |
| payment.transactions.transaction.info.cvd.tax_id | string | ИНН |
| payment.transactions.transaction.info.cvd.firstname | string | Имя |
| payment.transactions.transaction.info.cvd.lastname | string | Фамилия |
| payment.transactions.transaction.info.cvd.middlename | string | Отчество |
| payment.transactions.transaction.info.aml | string | Дані про учасників платежу для фінансового моніторингу. Можуть дублюватись з даними в request.body.info.cvd |
| payment.transactions.transaction.info.aml.sender_firstname | string | Ім'я відправника |
| payment.transactions.transaction.info.aml.sender_middlename | string | По-батькові відправника |
| payment.transactions.transaction.info.aml.sender_lastname | string | Прізвище відправника |
| payment.transactions.transaction.info.aml.sender_identification_number | string | ІПН (Індивідуальний податковий номер) / Код ЄДРПОУ (Єдиного державного реєстру підприємств та організацій України) відправника |
| payment.transactions.transaction.info.aml.sender_document | string | Номер документа відправника |
| payment.transactions.transaction.info.aml.sender_address | string | Адреса відправника |
| payment.transactions.transaction.info.aml.sender_account_number | string | Розрахунковий рахунок відправника |
| payment.transactions.transaction.info.aml.receiver_firstname | string | Ім'я отримувача |
| payment.transactions.transaction.info.aml.receiver_middlename | string | По-батькові отримувача |
| payment.transactions.transaction.info.aml.receiver_lastname | string | Прізвище отримувача |
| payment.transactions.transaction.info.aml.receiver_identification_number | string | ІПН (Індивідуальний податковий номер) / Код ЄДРПОУ (Єдиного державного реєстру підприємств та організацій України) отримувача |
| payment.transactions.transaction.info.aml.receiver_document | string | Номер документа отримувача |
| payment.transactions.transaction.info.aml.receiver_address | string | Адреса отримувача |
| payment.transactions.transaction.info.aml.receiver_account_number | string | Розрахунковий рахунок отримувача |
| payment.transactions.transaction.info.additional_tokens.mcts_vts | bool | Тип токену. Якщо встановлено, то разом з токеном tokly створиться токен mcts/vts. |
| payment.transactions.transaction.info.allowed_card_types | array | Дозволені типи карт для операції (можливі значення: mastercard, visa) |
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <payment> <auth> <mch_id>2023</mch_id> <salt>c2cbe9bbbce5c6870475b7c649da8205c30ffe65</salt> <sign>2b99f7b6a8ea065f6a28bc86eb2de84bffb2b887a2a9c9dbee5818b46f96e093cc397a2755f8663a745672bdf654e20e001853e1f780f3a3fa23ee9189046fac</sign> </auth> <urls> <good>http://www.example.com/ok/</good> <bad>http:// www.example.com/fail/</bad> </urls> <card> <token>MWNiNTE3...zNWNhMzFjNzAw</token> або <cdata>VWRlE...cd7EC0dWprsA=.cHFqQ6JGokgQVOAQdNgLNw==</cdata> </card> <transactions> <transaction> <amount>55</amount> <currency>UAH</currency> <desc>Покупка товара/услуги</desc> <info>{"dogovor":123456, "user_id": 654321, "cvd":{"tax_id":123456789, "firstname":"name", "lastname":"surname", "middlename":"patronymic"}}</info> <smch_id>4301</smch_id> </transaction> </transactions> <lifetime>24</lifetime> <lang>ua</lang> </payment>
| Поле | Тип | Опис |
|---|---|---|
| payment | element | Початковий елемент |
| payment.pid | integer | ID платежу в системі iPay |
| payment.status | integer | Статус платежу |
| payment.url | string | URL по якому треба перейти для здійснення оплати |
| payment.auth.salt | string | Сіль підпису |
| payment.auth.sign | string | Підпис запиту |
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <payment> <pid>12345678</pid> <status>1</status> <salt>5eb902aad2f4aa7f7955d067cdb769c53aebf1e9</salt> <sign>0c8698119b846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393</sign> <url>https://tokly.ipay.ua/a1f7e6a6ced6fc72d4dbb48da6babc7d2ca89ac2</url> </payment>
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
Запит викониється лише тоді, коли мерчант працює з предавторизацією платежа
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.pmt_id | integer | ID платежу в системі iPay |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2" }, "action":"Completion", "body":{ "pmt_id":12345678 } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt_id | numeric | ID платежу в системі iPay |
| response.status | string | Статус платежу |
| response.sale_date | date | Дата виконання авторизації/завершення платежу |
| response.transactions | element | Елемент транзакцій |
| response.transactions.[0] | element | Масив транзакцій, у порядку зростання |
| response.transactions.[0].trn_id | numeric | Номер транзакції в системі iPay |
| response.transactions.transaction.smch_rr | numeric | Розрахунковий рахунок юридичної особи |
| response.transactions.transaction.smch_mfo | numeric | МФО юридичної особи |
| response.transactions.transaction.smch_okpo | numeric | ОКПО юридичної особи |
| response.transactions.transaction.smch_bank | string | Банк юридичної особи |
| response.transactions.transaction.invoice | numeric | Сума платежу, у копійках |
| response.transactions.transaction.amount | numeric | Сума до сплати (з урахуванням комісії), у копійках |
| response.rrn | string | Ідентифікатор платежу в банку-еквайрі |
| response.auth_code | string | Код авторизації в банку-еквайрі |
| response.bank_acquirer_name | string | Назва банку-еквайра |
| response.card_mask | string | Маска картки, яка використовувалась в платежі |
| response.auth.salt | string | Сіль підпису |
| response.auth.sign | string | Підпис запиту |
| Опціональні поля | ||
| response.terminal_id | string | ID терміналу в банку еквайрі, який використовувався для платежу |
{ "response":{ "pmt_id":12345678, "status":5, "sale_date":"2021-07-22 00:40:39", "transactions":[ { "trn_id":194398934, "smch_rr":123, "smch_mfo":456, "smch_okpo":789, "smch_bank":"Bank name", "invoice":30, "amount":30 } ], "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"89ac2ceffc9ae0eacb2a841b95f058d0f2ce8d97a4b636ac8fa82d9a64677136707943efd4464465556588725b7e3cc2ffc7a2ddbc281b32c8972a470e4995a0" } }
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
На першому кроці створюється платіж за допомогою запросу PaymentCreate в якому повинна бути сформована одна
транзакція
з загальною сумою оплати і юрособою самого мерчанта.
Після того як користувач оплачує платіж, відбувається попередня авторизація коштів з карти, яка остаточно
буде
списана банком по закінченню 14 днів.
До цього моменту потрібно обов'язково подати запит на завершення оплати.
При формуванні транзакцій на завершення оплати (Completion) необхідно дотримуватися кількох правил:
1. Повинна бути сформована 1 або кілька транзакцій
2. Загальна сума транзакцій не повинна бути більше ніж при створенні платежу, інакше буде помилка.
Виправляти помилку слід шляхом подачі запиту з коректною сумою.
3. Якщо сума транзакцій буде менше, відбудеться часткова відміна по платежу і різниця повернеться на карту.
4. Для повної відміни, не в день сплати платежу, необхідно звертатися на пошту support@ipay.ua
5. При частковому скасуванню платежу, повне скасування можливе алє залежить від банку екваера, та вирішується на
етапі підключення
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.pmt_id | integer | ID платежу в системі iPay |
| request.body.transactions | integer | text |
| request.body.transactions | element | Елемент транзакцій, мають структуру масиву, та нумеруются по порядку [0],[1],[2]... |
| request.body.transactions[0]amount | numeric | Сума у копійках |
| request.body.transactions[0]smch_id | numeric | Юридична особа, на користь якої здіюйснюється операція |
| request.body.transactions[0]desc | string | Опис платежу |
| request.body.transactions[0]info | object | Інформація до платежу |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2" }, "action":"Completion", "body":{ "pmt_id":107648324, "transactions":[ { "amount":20, "smch_id":111, "desc":"rewrdesc1", "info":{ "dogovor":12345 } }, { "amount":25, "smch_id":222, "desc":"rewrdesc2", "info":{ "dogovor":67890 } } ] } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt_id | numeric | ID платежу в системі iPay |
| response.status | string | Статус платежу |
| response.sale_date | date | Дата виконання авторизації/завершення платежу |
| response.transactions | element | Елемент транзакцій |
| response.transactions.[0] | element | Масив транзакцій, у порядку зростання |
| response.transactions.[0].trn_id | numeric | Номер транзакції в системі iPay |
| response.transactions.transaction.smch_rr | numeric | Розрахунковий рахунок юридичної особи |
| response.transactions.transaction.smch_mfo | numeric | МФО юридичної особи |
| response.transactions.transaction.smch_okpo | numeric | ОКПО юридичної особи |
| response.transactions.transaction.smch_bank | string | Банк юридичної особи |
| response.transactions.transaction.invoice | numeric | Сума платежу, у копійках |
| response.transactions.transaction.amount | numeric | Сума до сплати (з урахуванням комісії), у копійках |
| response.auth.salt | string | Сіль підпису |
| response.auth.sign | string | Підпис запиту |
{ "response":{ "pmt_id":12345678, "status":5, "sale_date":"2021-09-09 23:14:04", "transactions":[ { "trn_id":98765, "smch_rr":12345, "smch_mfo":23456, "smch_okpo":34567, "smch_bank":"BANK_NAME", "invoice":20, "amount":20 }, { "trn_id":87654, "smch_rr":112345, "smch_mfo":223456, "smch_okpo":324567, "smch_bank":"BANK_NAME", "invoice":25, "amount":25 } ], "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"ea572465324fad74234744187898128b01914512085feb8035245e8d803e70123e5fe7a8130d7237c6311bbf6d56b83f1023a5ea2e9fb9fdb02107dbc2250e69" } }
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
Запит виконується лише тоді, коли треба заявити в платіжну систему успішний платіж який раніше був успішно виконаний але не заявлений (статус 13) і може потребувати змін по розрахунку з юр.особами.
При формуванні транзакцій в Declare необхідно щоб загальна сума цих транзакцій була така сама як сума в invoice при створенні платежу, а також щоб цей платіж мав лише одну транзакцію.
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.pmt_id | integer | ID платежу в системі iPay |
| request.body.transactions | integer | text |
| request.body.transactions | element | Елемент транзакцій, мають структуру масиву, та нумеруются по порядку [0],[1],[2]... |
| request.body.transactions[0]amount | numeric | Сума у копійках |
| request.body.transactions[0]smch_id | numeric | Юридична особа, на користь якої здіюйснюється операція |
| request.body.transactions[0]desc | string | Опис платежу |
| request.body.transactions[0]info | object | Інформація до платежу |
{
"request": {
"auth": {
"mch_id": 2023,
"salt": "5eb902aad2f4aa7f7955d067cdb769c53aebf1e9",
"sign": "0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2"
},
"action": "Declare",
"body": {
"pmt_id": 107648324,
"transactions": [
{
"amount": 20,
"smch_id": 111,
"desc": "rewrdesc1",
"info": {
"dogovor": 12345
}
},
{
"amount": 25,
"smch_id": 222,
"desc": "rewrdesc2",
"info": {
"dogovor": 67890
}
}
]
}
}
}
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt_id | numeric | ID платежу в системі iPay |
| response.status | string | Статус платежу |
| response.sale_date | date | Дата виконання авторизації/завершення платежу |
| response.transactions | element | Елемент транзакцій |
| response.transactions.[0] | element | Масив транзакцій, у порядку зростання |
| response.transactions.[0].trn_id | numeric | Номер транзакції в системі iPay |
| response.transactions.transaction.smch_rr | numeric | Розрахунковий рахунок юридичної особи |
| response.transactions.transaction.smch_mfo | numeric | МФО юридичної особи |
| response.transactions.transaction.smch_okpo | numeric | ОКПО юридичної особи |
| response.transactions.transaction.smch_bank | string | Банк юридичної особи |
| response.transactions.transaction.invoice | numeric | Сума платежу, у копійках |
| response.transactions.transaction.amount | numeric | Сума до сплати (з урахуванням комісії), у копійках |
| response.auth.salt | string | Сіль підпису |
| response.auth.sign | string | Підпис запиту |
| Опціональні поля | ||
| response.terminal_id | string | ID терміналу в банку еквайрі, який використовувався для платежу |
{
"response": {
"pmt_id": 12345678,
"status": 5,
"sale_date": "2021-09-09 23:14:04",
"transactions": [
{
"trn_id": 98765,
"smch_rr": 12345,
"smch_mfo": 23456,
"smch_okpo": 34567,
"smch_bank": "BANK_NAME",
"invoice": 20,
"amount": 20
},
{
"trn_id": 87654,
"smch_rr": 112345,
"smch_mfo": 223456,
"smch_okpo": 324567,
"smch_bank": "BANK_NAME",
"invoice": 25,
"amount": 25
}
],
"salt": "5eb902aad2f4aa7f7955d067cdb769c53aebf1e9",
"sign": "ea572465324fad74234744187898128b01914512085feb8035245e8d803e70123e5fe7a8130d7237c6311bbf6d56b83f1023a5ea2e9fb9fdb02107dbc2250e69"
}
}
Запит може бути виконано лише для успішного платежу.
Доступні статуси:
3(авторизовано) - лише для мерчантів, які працюють з предавторизацією;
5(успішний) - для доступу до повернень у день відмінний від дня платежу, звертайтесь у підримку;
13(успішний без заявлення) - для доступу до повернень у день відмінний від дня платежу, звертайтесь у підримку;
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | numeric | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body.pmt_id | numeric | ID платежу в системі iPay |
| Опціональні поля | ||
| request.body.amount | numeric | Сума відміни/повернення, якщо потрібно, щоб воно було частковим(Опціонально, для платежів з однією транзакцією) |
| request.body.transactions | numeric | Масив з транзакціями, якщо потрібно відмінити/повернути частину однієї з них(Опціонально, для платежів з кількома транзакціями) |
| request.body.transactions[].trn_id | numeric | ID транзакції |
| request.body.transactions[].amount | numeric | Сума транзакції, яку потрібно повернути |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2" }, "action":"Reversal", "body":{ "pmt_id":12345678, } } }
| Поле | Тип | Опис |
|---|---|---|
| payment | element | Початковий елемент |
| payment.pid | numeric | ID платежу в системі iPay |
| payment.status | string | Статус платежу |
| payment.sale_date | date | Дата виконання авторизації/завершення платежу |
| payment.transactions | element | Елемент транзакцій |
| payment.transactions.transaction | element | Елемент транзакції |
| payment.transactions.transaction.trn_id | numeric | Номер транзакції в системі iPay |
| payment.transactions.transaction.smch_rr | numeric | Розрахунковий рахунок юридичної особи |
| payment.transactions.transaction.smch_mfo | numeric | МФО юридичної особи |
| payment.transactions.transaction.smch_okpo | numeric | ОКПО юридичної особи |
| payment.transactions.transaction.smch_bank | string | Банк юридичної особи |
| payment.transactions.transaction.invoice | numeric | Сума платежу, у копійках |
| payment.transactions.transaction.amount | numeric | Сума до сплати (з урахуванням комісії), у копійках |
| payment.auth.salt | string | Сіль підпису |
| payment.auth.sign | string | Підпис запиту |
{ "response":{ "pmt_id":107647782, "status":9, "sale_date":"2021-09-09 23:05:07", "transactions":[ { "trn_id":212348795, "smch_rr":112345, "smch_mfo":223456, "smch_okpo":324567, "smch_bank":"BANK_NAME", "invoice":100, "amount":100 } ], "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"2ab7ee2e5ea7539ed7f2c222ad1e626bda4420cb45d03b7578aca247c386b1d664ff6873e8e39f4413b922994ce986555a9e806ed919ec6490f768409a8d3f85" } }
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
Запит повинен містити у структурі card одночасно лише pan або token
Обмеження по картах: підтримуються лише українські карти, VISA обо MASTERCARD
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.invoice | integer | Сума у копійках |
| request.body.ext_id | string | Унікальний ідентифікатор оплати в системній мерчанта (максимальна довжина - 50 символів) |
| request.body.card | element | Елемент картки |
| request.body.card.pan | string | пан карти |
| request.body.card.token | string | токен карти |
| Опціональні поля | ||
| request.body.info | json | Інформація до платежу, надається мерчантом |
| request.body.sender | json | Реквізити відправника (опис після прикладу запиту), обов'язковий у випадку наявності request.body.receiver |
| request.body.receiver | json | Реквізити одержувача (опис після прикладу запиту), обов'язковий у випадку наявності request.body.sender |
{ "request":{ "auth":{ "mch_id":1234, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"a12a4d5eb7da121bc04d360a5c11fd7b" }, "action":"A2CPay", "body":{ "invoice": 100, "ext_id": "1234567890ABCD", "info":{"info_test":"value_info"} "card":{ "pan": "1234567890123456", "token": "MWNiNTE3...zNWNhMzFjNzAw", } } } }
| Поле | Тип | Опис |
|---|---|---|
| request.body.sender | element | Початковий елемент відправника |
| request.body.sender.lastname | string | Прізвище відправника |
| request.body.sender.firstname | string | Ім'я відправника |
| request.body.sender.middlename | string | По батькові відправника |
| request.body.sender.document | string | Номер паспорта відправника (наприклад: АН123456) |
| request.body.sender.address | string | Адреса відправника (наприклад: Київ, вул. Тестова, 10) |
| request.body.sender.identificationNumber | string | (опціонально) ІПН(Індивідуальний податковий номер)/ЄДРПОУ(ідентифікаційний код суб'єкта Єдиного державного реєстру підприємств України) |
| request.body.sender.accountNumber | string | (опціонально) розрахунковий рахунок відправника(фіз. особа/підприємство) |
| request.body.receiver | element | Початковий элемент одержувача |
| request.body.receiver.lastname | string | Прізвище одержувача |
| request.body.receiver.firstname | string | Ім'я одержувача |
| request.body.receiver.middlename | string | По батькові одержувача |
| request.body.receiver.address | string | Адреса одержувача (наприклад: Київ, вул. Тестова, 10) |
| request.body.receiver.identificationNumber | string | (опціонально) ІПН(Індивідуальний податковий номер)/ЄДРПОУ(ідентифікаційний код суб'єкта Єдиного державного реєстру підприємств України) |
| request.body.receiver.accountNumber | string | (опціонально) розрахунковий рахунок відправника(фіз. особа/підприємство) |
| request.body.receiver.document | string | (опціонально) Номер документа відправника (например: АН123456) |
{ "request":{ "auth":{ "mch_id":1234, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"a12a4d5eb7da121bc04d360a5c11fd7ba12a4d5eb7da121bc04d360a5c11fd7ba12a4d5eb7da121bc04d360a5c11fd7ba12a4d5eb7da121bc04d360a5c11fd7b" }, "action":"A2CPay", "body":{ "invoice":100, "ext_id":"1234567890ABCD", "info":{"info_test":"value_info"}, "card":{ "pan":"1234567890123456" }, "sender":{ "lastname":"Фамилия отправителя", "firstname":"Имя отправителя", "middlename":"Отчество отправителя", "document":"Номер паспорта отправителя", "address":"Адрес отправителя" }, "receiver":{ "lastname":"Фамилия получателя", "firstname":"Имя получателя", "middlename":"Отчество получателя", "address":"Адрес получателя" } } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt_id | integer | ID платежу в системі iPay |
| response.status | integer | Статус платежу |
| response.receipt | integer | Посилання на квитанцію |
| response.invoice | integer | Сума, яка зарахована на карту |
| response.amount | integer | Сума платежу з урахуванням коміссії |
| response.res_auth_code | integer | Код відмови по операції |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response":{ "pmt_id":44482723, "status":5, "invoice":100, "amount":100, "res_auth_code":0, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2" } }
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
Запит повинен містити у структурі одночасно лише ext_id або pmt_id (В Sandbox середовищі може використовуватись лише pmt_id)
ВАЖЛИВО: Фінальним статусом може вважатися тільки 4 (неуспіх) або 5 (успіх). У разі отримання відмінної від неуспіху або успіху відповіді необхідно виконувати перезапит статусу до отримання кінцевого статусу операції.
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.ext_id | string | Унікальний ідентифікатор оплати в системній мерчанта (максимальна довжина - 50 символів) |
| Опціональні поля | ||
| request.body.pmt_id | integer | ID платежу в системі iPay |
{ "request":{ "auth":{ "mch_id":1234, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"a12a4d5eb7da121bc04d360a5c11fd7ba12a4d5eb7da121bc04d360a5c11fd7ba12a4d5eb7da121bc04d360a5c11fd7ba12a4d5eb7da121bc04d360a5c11fd7b" }, "action":"A2CPaymenStatus", "body":{ "ext_id":"01234567893ABCDEF" } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt_id | integer | ID платежу в системі iPay |
| response.status | integer | Статус платежу |
| response.receipt | integer | Посилання на квитанцію |
| response.invoice | integer | Сума, яка зарахована на карту |
| response.amount | integer | Сума платежу з урахуванням коміссії |
| response.res_auth_code | integer | Код відмови по операції |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response":{ "pmt_id":44482723, "status":5, "invoice":100, "amount":100, "res_auth_code":0, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2" } }
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
{
"request": {
"auth": {
"mch_id": 2995,
"salt": "aed333978bf435e0eae294c30611a761fcdafa99",
"sign": "ceda2a4bc55c17a5ed2aeebf119ff3ded3649a9b730462171671df4949dd2459baf87192af0df7098f0b2dabb00fd02c02980f51d83503f59db16b446a40c9c0"
},
"action": "A2CBalance"
}
}
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.current_balance | integer | Поточний баланс мерчанта в копійках |
| response.overdraft | integer | Поточний овердрафт мерчанта в копійках |
| response.credit | integer | Поточний зустрічний оборот мерчанта в копійках |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{
"response": {
"current_balance": -30,
"overdraft": 1000,
"credit": 0,
"salt": "6af2952a2f1fe5e2c0385f99e84a9a05274328ef",
"sign": "0adb98c05edf8e86db11046ca25af4a433a03a3b776bb28f318f57852620319f09c71df06809904cda0fcb288bdfec5887fc504a691a82684a1db817afdc09c7"
}
}
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| Опціональні поля | ||
| request.body.pmt_ids | integer[] | Масив ID платежів в системі iPay |
| request.body.ext_ids | integer[] | Масив унікальних ідентифікаторів оплати в системній мерчанта |
| request.body.info_field | string | Назва поля із info в якому міститься призначення платежу |
Потрібно обов'язково передати одне з полів ext_ids або pmt_ids
{
"request": {
"auth": {
"mch_id": 2995,
"salt": "aed333978bf435e0eae294c30611a761fcdafa99",
"sign": "ceda2a4bc55c17a5ed2aeebf119ff3ded3649a9b730462171671df4949dd2459baf87192af0df7098f0b2dabb00fd02c02980f51d83503f59db16b446a40c9c0"
},
"action": "A2CInvoice",
"body": {
"ext_ids": [
"01234593ABCDEA",
"11234593ABCDEB",
"21234593ABCDEC"
],
"info_field": "pay_description"
}
}
}
У відповідь повертається файл PDF.
Content-Type: application/pdf Content-disposition: inline; filename="invoice-3-2812-iPay-ua.pdf"
Списання коштів на користь мерчанта без участі картхолдера
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
Якщо мерчант працює з предавторизацією, response.status = 3 у відповіді на запрос, або у нотифікації,
то для успішного завершення платежа потрібно виконувати запит Completion (Завершити
платіж)
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.transactions | array | Масив елементів транзакцій |
| request.body.transactions[0] | element | Елемент транзакції |
| request.body.transactions[0]amount | integer | Сума у копійках |
| request.body.transactions[0]desc | string | Опис платежу |
| request.body.transactions[0]info | array | Інформація до платежу, надається мерчантом при створенні |
| request.body.card | element | Елемент картки |
| request.body.card.token | string | Токен карти |
| Додаткові поля | ||
| request.body.transactions[0]smch_id | integer | Юридична особа, на користь якої здіюйснюється операція |
| request.body.ext_id | string | Унікальний ідентифікатор оплати в системі мерчанта (максимальна довжина - 50 символів) |
| request.body.card.token_type | string | Тип токену. Можливі варіанти: tokly, mcts, vts. |
| request.body.aml | string | Дані про учасників платежу для фінансового моніторингу. В майбутньому може стати обов'язковим. |
| request.body.aml.sender_firstname | string | Ім'я відправника |
| request.body.aml.sender_middlename | string | По-батькові відправника |
| request.body.aml.sender_lastname | string | Прізвище відправника |
| request.body.aml.sender_identification_number | string | ІПН (Індивідуальний податковий номер) / Код ЄДРПОУ (Єдиного державного реєстру підприємств та організацій України) відправника |
| request.body.aml.sender_document | string | Номер документа відправника |
| request.body.aml.sender_address | string | Адреса відправника |
| request.body.aml.sender_account_number | string | Розрахунковий рахунок відправника |
| request.body.aml.receiver_firstname | string | Ім'я отримувача |
| request.body.aml.receiver_middlename | string | По-батькові отримувача |
| request.body.aml.receiver_lastname | string | Прізвище отримувача |
| request.body.aml.receiver_identification_number | string | ІПН (Індивідуальний податковий номер) / Код ЄДРПОУ (Єдиного державного реєстру підприємств та організацій України) отримувача |
| request.body.aml.receiver_document | string | Номер документа отримувача |
| request.body.aml.receiver_address | string | Адреса отримувача |
| request.body.aml.receiver_account_number | string | Розрахунковий рахунок отримувача |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2" }, "action":"Debiting", "body":{ "ext_id": "AB123-456-789", "transactions": [ { "smch_id": 2921, "amount": 50, "desc": "transaction 1", "info": { "dogovor": 12345 } }, { "smch_id": 2922, "amount": 150, "desc": "transaction 2", "info": { "dogovor": 12345 } } ], "card":{ "token": "MWNiNTE3...zNWNhMzFjNzAw" } } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt_id | integer | ID платежу в системі iPay |
| request.ext_id | string | Унікальний ідентифікатор оплати в системі мерчанта (опціонально) |
| response.bnk_error_note | string | Код помилки. Пояснення кодів описано тут |
| response.status | integer | Статус платежу |
| response.transactions | array | Масив елементів транзакцій |
| response.transactions[0] | element | Елемент транзакції |
| response.transactions[0]trn_id | integer | Номер транзакції в системі iPay |
| response.transactions[0]smch_rr | integer | Розрахунковий рахунок юридичної особи |
| response.transactions[0]smch_mfo | integer | МФО юридичної особи |
| response.transactions[0]smch_okpo | integer | ОКПО юридичної особи |
| response.transactions[0]smch_bank | string | Банк юридичної особи |
| response.transactions[0]invoice | integer | Сума платежу, у копійках |
| response.transactions[0]amount | integer | Сума до сплати (з урахуванням комісії), у копійках |
| response.rrn | string | Ідентифікатор платежу в банку-еквайрі |
| response.auth_code | string | Код авторизації в банку-еквайрі |
| response.bank_acquirer_name | string | Назва банку-еквайра |
| response.card_mask | string | Маска картки, яка використовувалась в платежі |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
| Опціональні поля | ||
| response.terminal_id | string | ID терміналу в банку еквайрі, який використовувався для платежу |
{ "response":{ "pmt_id":44482724, "ext_id": "AB123-456-789", "status":5, "transactions":[ { "trn_id":194398934, "smch_rr":123, "smch_mfo":456, "smch_okpo":789, "smch_bank":"Bank name", "invoice":50, "amount":50 }, { "trn_id":194398935, "smch_rr":123, "smch_mfo":456, "smch_okpo":789, "smch_bank":"Bank name", "invoice":150, "amount":150 } ], "salt":"5e955d067cd3aebfb7ad2f4aa7f69c51b902a7e9", "sign":"0ef8d7588d9b91a1a48de9ca241bc60b6f286890ae58cef452c0b6ef52d1fd72d5f61c4695039c4512caffda945d77496fdb98e766ba69b0a1624d7a13687cd2" } }
{ "response": { "pmt_id": 162136260, "status": 4, "bnk_error_note": "42-insufficient_funds", "transactions":[ { "trn_id": 194398934, "smch_rr": 123, "smch_mfo": 456, "smch_okpo": 789, "smch_bank": "Bank name", "invoice": 50, "amount": 50 }, { "trn_id": 194398935, "smch_rr": 123, "smch_mfo": 456, "smch_okpo": 789, "smch_bank": "Bank name", "invoice": 150, "amount": 150 } ], "salt": "e6c468877d50c07fea027b2708a57fc36fa56d0f", "sign": "708cad33a5db5626a11bb4300349a9bf0989718e7d6d336ccdab5516eb3d1350b7ad1fb1493569948650e19a5a1b061eca9f9ebf021d2c0efb" } }
Отримання списку токенов з прив'язкою до даних користувача
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| Опціональні поля | ||
| request.body.bind | string | Значення з котрим було зв'язано токен |
| request.body.cdata | string | Номер картки, закодований як описано у відповідному розділі |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"5c11fd7ba12a4d5eb7da121bc04d360a5c11fd7b..." }, "action":"GetTokenList", "body":{ "bind":"987654987654ABC" } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.bind | string | Значення з яким пов'язаний токен |
| response.cards | array | Массив елементів карт |
| response.cards[0] | element | Елемент карти |
| response.cards[0]card_mask | string | Маска карти |
| response.cards[0]tokens | string | Масив токенів карти |
| response.cards[0]tokens[0] | element | Елемент токену |
| response.cards[0]tokens[0]type | string | Тип токену. Можливі варіанти: tokly, mcts, vts |
| response.cards[0]tokens[0]token | string|null | Токен |
| response.cards[0]tokens[0]status | string | Статус токену. Можливі варіанти: active, inactive, deleted |
| response.cards[0]tokens[0]card_data_expire_date | string | Дата видалення даних про картку. У випадку, якщо дані вже видалено, значення буде 'Already expired' |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response":{ "bind":"987654987654ABC", "cards": [ { "card_mask": "537591******6080", "tokens": [ { "type": "tokly", "token": "MWIxYjc1MDRiNjI1M2RiYmE4ODIzMGU2MjEzMjE2MmQyNDJiNTc5NzM0MmNkM2U2NWNlNmQ3YjgyZmZiNTEyZTAw", "status": "active" }, { "type": "mcts", "token": "YzdmZGVjNGI4OTRkNGM3YTI0ZDQ2NTY5NDdjMGM3NzBhZDYwYjgzNDg0YjNmOTU1NzMwMzg1NGYxM2U0ZDk1YzAw", "status": "active" } ] } ], "salt":"2e6a36e370ddc3c6f25c80c111a9e86428533fdd", "sign":"b7579f34db23de5446d899d8f2985c9cb001f727..." } }
Отримання статусу платежу який здійснено мерчантом
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
Якщо у відповіді статус платежу який не задокументовано, прохання звертатись до служби підтримки iPay.ua
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.pmt_id | integer | ID платежу в системі iPay |
| request.body.ext_id | string | Унікальний ідентифікатор оплати в системі мерчанта |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"5c11fd7ba12a4d5eb7da121bc04d360a5c11f..." }, "action":"GetPaymentStatus", "body":{ "pmt_id":12345678 } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.pmt | element | Початковий єлемент платежу |
| response.pmt.pmt_id | integer | ID платежу в системі iPay |
| response.pmt.ext_id | string | Унікальний ідентифікатор оплати в системі мерчанта |
| response.pmt.status | integer | Статус платежу |
| response.pmt.card_mask | string | Маскована карта |
| response.pmt.invoice | integer | Сума платежу без комісії |
| response.pmt.amount | integer | Сума платежу з комісією |
| response.pmt.desc | string | Призначення платежу |
| response.pmt.bnk_error_group | integer | Група помилки |
| response.pmt.bnk_error_note | string | Текстове визначення помилки |
| response.pmt.init_date | string | Дата створення платежу |
| response.pmt.rrn | string | Ідентифікатор платежу в банку-еквайрі |
| response.pmt.auth_code | string | Код авторизації в банку-еквайрі |
| response.pmt.bank_acquirer_name | string | Назва банку-еквайра |
| response.pmt.card_mask | string | Маска картки, яка використовувалась в платежі |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response":{ "pmt":{ "pmt_id":49771598, "status":4, "card_mask":"414950******2162", "invoice":10000, "amount":10000, "desc":"Тест - 15%", "bnk_error_group":51, "bnk_error_note":"51-verification_error_3d_2d", "init_date":"2020-02-28 14:45:19" }, "salt":"68fc5a711ea2e90019b899ec09091a4a5221fccf", "sign":"2a7429c667afececbdc59faffc236919db32a..." } }
Видалення токена запобігає створювання та оплат за данним токеном.
Видалений токен можливо створити повторно
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.token | integer | Токен карти |
| Опціональні поля | ||
| request.body.token_type | string | Тип токену. Можливі варіанти: tokly, mcts, vts. За замовчуванням: tokly |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"5c11fd7ba12a4d5eb7da121bc04d360a5c11f..." }, "action":"DeleteToken", "body":{ "token":"YjczODGhYmIxYTg4YzljFTQ2MjllODdlOTI1NTZhMjL1OWYxMTBmZGU3ZGJjADUzMWVjYTEwYjg0ZGM1YjJlNTAw" } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.token | string | Токен карти |
| response.delete_status | boolean | Статус видалення токена |
| response.message | string | Повідомлення про видалення токена |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response":{ "token":"YjczODGhYmIxYTg4YzljFTQ2MjllODdlOTI1NTZhMjL1OWYxMTBmZGU3ZGJjADUzMWVjYTEwYjg0ZGM1YjJlNTAw", "delete_status":true, "message":"Successfully deleted", "salt":"71e3f85e6e30347f8337402694acc0047a6b9e69", "sign":"d1acfd18c1c79671eaf147b3a21b3af11d6ca5da686b4158f6eb214d6c6aba17ff475533b6cf3e5a2f2ad4b0608671463d753da9c8ec12820d40a65d2fc8a511" } }
Отримання даних про власника карти доступно лише для карт Приватбанку, Монобанку та ПУМБ
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.cdata | string | Закодовані картданні |
| request.body.cvd | element | Елемент Card Verification Data |
| request.body.cvd.firstname | string | Имя |
| request.body.cvd.lastname | string | Фамилия |
| request.body.cvd.middlename | string | Отчество |
| request.body.cvd.phone_number | string | Номер телефону у форматі 380YYXXXXXXX |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"a12a4d5eb7da121bc04d360a5c11fd7b..." }, "action":"GetCardholderName", "body":{ "cdata":"omhlJHD00QZk32WstDHpAOGHV+bkud62nXI=.cyDAn2Q4QA2L++sICPciVw==", "cvd":{ "tax_id":1234567890, "firstname":"name", "lastname":"surname", "middlename":"patronymic", "phone_number":380501234567 } } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.card_holder | string | Дані про власника карти |
| response.card_holder.FIO | string | ПІБ власника карти |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response": { "card_holder": { "FIO": "name surname patronymic" }, "salt": "71e3f85e6e30347f8337402694acc0047a6b9e69", "sign": "d1acfd18c1c79671eaf147b3a21b3af11d6ca5da686b4158f6eb214d6c6aba17ff475533b6cf3e5a2f2ad4b0608671463d753da9c8ec12820d40a65d2fc8a511" } }
| Поле | Тип | Опис |
|---|---|---|
| payment | element | Початковий елемент |
| payment.pid | integer | ID платежу в системі iPay |
| payment.status | string | Статус платежу |
| payment.sale_date | date | Дата виконання авторизації/завершення платежу |
| payment.transactions | element | Елемент транзакцій |
| payment.transactions.transaction | element | Елемент транзакції |
| payment.transactions.transaction.trn_id | integer | Номер транзакції в системі iPay |
| payment.transactions.transaction.smch_rr | integer | Розрахунковий рахунок юридичної особи |
| payment.transactions.transaction.smch_mfo | integer | МФО юридичної особи |
| payment.transactions.transaction.smch_okpo | integer | ОКПО юридичної особи |
| payment.transactions.transaction.smch_bank | string | Банк юридичної особи |
| payment.transactions.transaction.invoice | integer | Сума платежу, у копійках |
| payment.transactions.transaction.amount | integer | Сума до сплати (з урахуванням комісії), у копійках |
| payment.auth.salt | string | Сіль підпису |
| payment.auth.sign | string | Підпис запиту |
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <payment> <pid>12345678</pid> <status>9</status> <sale_date>2019-07-02 11:08:55</sale_date> <transactions> <transaction> <trn_id>11223344</trn_id> <smch_rr>26501014380602</smch_rr> <smch_mfo>300346</smch_mfo> <smch_okpo>37973023</smch_okpo> <smch_bank>ПАТ "АЛЬФА-БАНК"</smch_bank> <invoice>100</invoice> <amount>110</amount> </transaction> </transactions> <salt>a98688b38115a7b42f55ca74a2fe6f6fb536b57d</salt> <sign>566d16af0f9aeb12d055a2117160194ec0868ce418152a6ffb82a84037b4f28b9d345ee7f84a0374101771f891779af013e26e3540c26f4734d8717097f39bc9</sign> </payment>
Файл чеку буде отримано у відповіді на запит
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.pmt_id | integer | ID платежу в системі iPay |
{ "request": { "auth": { "mch_id": "2023", "salt": "80dae064b875c022a36a4e446a8d031b450690cf", "sign": "815abf8bffcdceef7c7a3f245b1140f80c51bbe7f1667e17451e56bfae246ef8ea44b5295dfbfd4b02c3b2043bef9158aebd0ed884c03702fe0d66743bfee8d7" }, "action": "GetReceipt", "body": { "pmt_id": "248983364" } } }
Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST
| Поле | Тип | Опис |
|---|---|---|
| request | element | Початковий елемент |
| request.auth | element | Елемент аутентифікації |
| request.auth.mch_id | integer | ID мерчанта |
| request.auth.salt | string | Сіль підпису |
| request.auth.sign | string | Підпис запиту |
| request.action | string | Назва запиту |
| request.body | element | Тіло запиту |
| request.body.token_type | string | Тип токену. Можливі варіанти: mcts, vts |
| request.body.token | string | Токен карти |
{ "request":{ "auth":{ "mch_id":2023, "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9", "sign":"a12a4d5eb7da121bc04d360a5c11fd7b..." }, "action":"GetCryptogram", "body":{ "token_type":"mcts", "token":"MWNiNTE3...zNWNhMzFjNzAw" } } }
| Поле | Тип | Опис |
|---|---|---|
| response | element | Початковий елемент |
| response.card_pan | string | PAN карти |
| response.card_expm | string | Термін дії картки (місяць) |
| response.card_expy | string | Термін дії картки (рік) |
| response.cryptogram | string | Криптограма |
| response.salt | string | Сіль підпису |
| response.sign | string | Підпис запиту |
{ "response": { "card_pan": 5375911111116080, "card_expm": 12, "card_expy": 2023, "cryptogram": "AD8jy6pDqkrrACdICtT+AoABFA==", "salt": "34f7f0c06e59cdacb8d5b827c5acded3a9fcbe21", "sign": "267f3f3f650ea84cabe7067192e35...c4db1789f3d5fd8fc597c5a41bce" } }
Посилання або e-mail для нотифікації прописується на стороні iPay.ua і може бути доданий або змінений в будь-який час за заявкою відповідального співробітника.
Нотифікації можуть бути наступних видів:
Всі нотифікації відправляються, як тільки операція з платником буде завершена. Уразі якщо, з якоїсь причини,
API не змогла відправити
даних за вказаними Вами адресами (наприклад, Ви проводили роботи з сервером, у Вас були перебої з доступом в
Інтернет і т.п.),
API намагатиметься відправити нотифікації кілька разів через кожні 2 хв.
У відповідь на нотифікацію мерчант повинен відправляти HTTP код 200 - що свідчить про успішну доставку нотифікації
УВАГА! Можлива ситуація, коли оповіщення по одному платежу надійдуть Вам кілька разів, це може бути
пов'язано з
неможливістю отримання підтвердження про отримання оповіщення з Вашого боку. У таких випадках Вам необхідно
коректно обробляти такі ситуації і не допускати обробки одного платежу кілька разів.
| Поле | Тип | Опис |
|---|---|---|
| payment | element | Початковий елемент з ID платежу в системі iPay |
| payment.ident | string | Унікальний ідентифікатор платежу, використовується при формуванні посилання |
| payment.status | string | Статус платежу |
| payment.amount | string | Загальна сума платежу |
| payment.currency | string | Код валюти |
| payment.timestamp | date | Дата виконання авторизації/завершення платежу у форматі UNIX-timestamp |
| payment.card_token | string | Токен карти |
| payment.transactions | element | Елемент транзакцій |
| payment.transactions.transaction | element | Елемент транзакції з номером транзакції в системі iPay |
| payment.transactions.transaction.mch_id | integer | ID мерчанта |
| payment.transactions.transaction.smch_id | integer | Юридична особа, на користь якої здіюйснюється операція |
| payment.transactions.transaction.invoice | integer | Сума платежу, у копійках |
| payment.transactions.transaction.amount | integer | Сума до сплати (з урахуванням комісії), у копійках |
| payment.transactions.transaction.desc | string | Опис платежу |
| payment.transactions.transaction.info | json object | Інформація до платежу, яка надавалась мерчантом при створенні |
| payment.auth.salt | string | Сіль підпису |
| payment.auth.sign | string | Підпис запиту |
| Опціональні поля | ||
| payment.card_is_prepaid | string | Карта препейд (значення 1) чи ні (значення 0) |
| payment.valid_tax_id | int | Валідний(значення 1) чи ні(значення 0) ІПН який було відправлено на один із запитів: CreateToken, CreateToken3DS, PaymentCreate. Може бути отримано лише для карт Альфа-банку |
| payment.card_holder | string | Повне ім'я власника картки, може бути отримано лише для карт Монобанку та Приватбанку |
| payment.payment_type | string | Можливі варіанти: Manual (внесення карткових даних в платіжну форму) / GooglePay / ApplePay. Підключення передачі даного поля здійснюється за кожним окремим мерчантом згідно заявки. |
| payment.transactions.transaction.info.external_cvd | json object | Доповнює дані, які були отримані при створені платежу, містить дані про власника картки в нашій системі, взаємовиключається з payment.card_holder |
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <payment id="12345678"> <ident>2b45db39f12555f3ef5dd129eea28d70c5a33ffc</ident> <status>5</status> <amount>110</amount> <currency>UAH</currency> <card>516874******1234</card> <card_token>MWNiNTE3...zNWNhMzFjNzAw</card_token> <card_is_prepaid>0</card_is_prepaid> <card_holder>ІВАНЕНКО ІВАН ІВАНОВИЧ</card_holder> <card_type>Mastercard</card_type> <bank_name>ПриватБанк</bank_name> <timestamp>1562660681</timestamp> <transactions> <transaction id="4567890"> <mch_id>1234</mch_id> <smch_id>4321</smch_id> <invoice>100</invoice> <amount>110</amount> <desc>Покупка услуги/товара</desc> <info>{"dogovor":123456789,"external_cvd":{"firstname":"Святослав","lastname":"Мельнійчук","middlename":"Сергійович"}}</info> </transaction> </transactions> <salt>f7be5bf13c644264df5757314946c6464627c7af</salt> <sign>23fd4c70bebe99549b4d9b078e2ddd69a5bdcce684c1a663eeb1036fd0d8c760408bb281df755228bc8d09ad93ec53b7516e01bbe0d39c27c4253d113156201a</sign> </payment>
Опис помилки повертається у текстовому форматі в полі response.error
Починаючи з версії 1.23, у відповіді також повертається error_code, а http-статус може бути відмінним від 200 або 500.
Приклад відповіді:
{
"response":{
"error":"missing required field desc",
"error_code":"U0"
}
}
| Текст помилки | Код помилки | http статус у відповіді | Причина |
|---|---|---|---|
| Загальні помилки | |||
| overall error | U0 | 200 | Загальна помилка, за більш детальною інформацією звертатися до iPay |
| request is not valid | R01 | 400 | Загальна помилка валідації запиту |
| missing required field desc | U0 | 200 | Не передане обов'язкове поле desc у запиті |
| Помилки запиту GetPaymentStatus | |||
| Payment is not found | P04 | 404 | Платіж з таким pmt_id не знайдено, або він відноситься до іншого mch_id |
| Помилки запиту Reversal | |||
| not enough turnover | U0 | 200 | Недостатньо обороту за день |
| no balance | U0 | 200 | Недостатньо коштів на балансі |
| no deposit for refund | U0 | 200 | Не знайдено депозит, за більш детальною інформацією звертайтеся до iPay |
| reversal amount must be fewer than payment invoice | U0 | 200 | Якщо за договором зовнішня комісія не повертається, то при частковому поверненні сума повернення повинна бути меншою ніж інвойс платежу |
| Помилки запиту Declare | |||
| invalid amount | U0 | 200 | Сума транзакцій відрізняється від суми вказаної при створенні платежу |
| payment already has more than one transaction | U0 | 200 | Платіж вже був раніше проведений з транзакціями більше однієї |
| missing required field smch_id | U0 | 200 | Не передане обов'язкове поле smch_id у запиті |
| Помилки запиту Debiting | |||
| debiting for VISA cards forbidden | U0 | 200 | Операція Debiting для карток VISA заборонена |
0 - Успішне зарахування 100 - Відмова, зверніться до банку-емітенту 101 - Закінчився термін дії картки 104 - Обмеження по картці (локальна, або заборонені операції) 106 - Картка заблокована 110 - Сума операції перевищує дозволену 111 - Невірний номер картки 116 - Сума операції перевищує дозволену 118 - Картка не активна, зверніться до банку-емітенту 120 - Обмеження по картці, зверніться до банку-емітенту 121 - Ліміти на картці (обмеження на інтернет розрахунки) 123 - Відмова банку-емітента/платіжної системи за кількістю операцій 124 - Обмеження по картці (заборонено законом) 200 - Невірний номер картки 202 - Невірний номер картки 208 - Загублена картка 209 - Вкрадена картка 907 - Банк-емітент не працює 908 - Банк не доступний 909 - Технічна несправність системи 600 - Цифровий підпис не валідний 601 - Відкритий ключ не знайдено 602 - Не коректний номер картко-приймача (не пройшла перевірка за алгоритмом Luhn) 603 - Обслуговуються картки емітовані тільки українськими банками 604 - Операція не може бути здійснена з технічних причин 605 - Перевищено ліміт одержувача по переказам 606 - Операція відхилена банком-емітентом картки одержувача 607 - Досягнутий ліміт по сумі поповнення на добу 608 - Досягнутий ліміт по сумі поповнення за місяць 609 - Досягнутий ліміт по кількості проведених платежів на одну картку на добу 610 - Досягнутий ліміт по кількості проведених платежів на одну картку за місяць 611 - Спроба провести платіж, що перевищує ліміт 612 - Платіж за заявкою вже здійснено з іншою сумою 613 - При підтверджені платежу передана інша дата проведення 614 - При підтверджені платежу переданий інший ід.системи партнера 615 - При підтверджені передана інша сума платежу 616 - При підтверджені переданий інший хеш номер картки 617 - карта внесена в серые списки 618 - превышен лимит получателя по количеству переводов 619 - карта получателя заблокирована по причине задолженности 620 - банк эмитент карты получателя недоступен 621 - банк эмитент карты получателя не может обработать операцию 622 - необходимо уточнить реквизиты карты получателя у банка эмитента 623 - карта получателя заблокирована банком эмитентом
| Значення поля status | Опис |
|---|---|
| 1 | Зареєстрований (в обробці) |
| 3 | Пред-авторизований. Платіж очікує завершення методом Completion. |
| 4 | Неуспішний |
| 5 | Успішний |
| 9 | Відмінений |
| 11 | Ручна обробка |
| 13 | Успішний платіж без заявлення в платіжну систему |
| 14 | Відмова системи безпеки |
| Код помилки | Причина | Повідомлення користувачу (ua) | Повідомлення користувачу (ru) |
|---|---|---|---|
| 41-eminent_decline | Операція відхилена банком емітентом | Платіж відхилено Банком, в якому у Вас обслуговується карта. Можливо, на карті спрацювали обмеження або ліміти на інтернет- операції. Рекомендуємо звернутись на гарячу лінію Вашого банку, щоб уточнити у оператора причину відмови. | Платеж отклонен Банком, в котором у Вас обслуживается карта. Возможно, на карте сработали ограничения либо лимиты на интернет- операции. Рекомендуем обратиться на горячую линию Вашего банка, чтобы уточнить у оператора причину отказа. |
| 42-insufficient_funds | Недостатньо коштів | Платіж відхилено Банком, в якому у Вас обслуговується карта. Так як, недостатньо коштів на рахунку. Рекомендуємо вказати меншу суму або використати іншу карту. | Платеж отклонен Банком, в котором у Вас обслуживается карта.Так как, недостаточно средств на карте. Рекомендуем указать меньшую сумму или использовать другую карту. |
| 43-limits_emitent | Перевищено ліміт операцій по карті - можливо картка не відкрита для оплати в інтернет | Неуспішний платіж, на Вашій карті спрацювал ліміти на інтернет - операції. Рекомендуємо звернутись на гарячу лінію банку, щоб оператор підвищив ліміти. | Неуспешный платеж, на Вашей карте сработали лимиты на интернет - операции. Рекомендуем обратиться на горячую линию банка, чтобы оператор повысил лимиты. |
| 44-limits_terminal | Перевищено ліміт Магазину або транзакції заборонені Магазину | Платіж підхилено Банком, за допомогою якого проводиться оплата. Так як, наш Банк - партнер встановив свої обмеження. | Платеж отклонен Банком, с помощью которого выполняется оплата. Так как, наш Банк-партнер установил свои ограничения. |
| 50-verification_error_CVV | Невірний CVV код | Платіж відхилено Банком, в якому у Вас обслуговується карта. Рекомендуємо звернутись на гарячу лінію Вашого банку, щоб уточнити у оператора причину відмови. | Платеж отклонен Банком, в котором обслуживается Ваша карта. Рекомендуем обратиться на горячую линию Вашего банка, чтобы уточнить у оператора причину отказа. |
| 51-verification_error_3d_2d | Невірний код підтвердження 3DS або сесія закінчилася | Платіж відхилено, так як, Ви не ввели код - підтвердження від Вашого банку. Рекомендуємо повторити оплату, ввівши новий код, який приходить на телефон, що закріплений за Вашою банківською картою. | Платеж отклонен, так как, Вы не ввели код - подтвержения от Вашего банка. Рекомендуем повторить оплату, введя новый код, который придёт на телефон, что закреплен за Вашей банковской картой. |
| 52-connection_error | Помилка сценарію | Платіж відхилено. Так як, у момент оплати не було зв’язку с Банком у якому у Вас обслуговується карта. Рекомендуємо повторити оплату через 2 хвилини. | Платеж отклонен, так как, в момент оплаты не было связи с Банком, в котором у Вас обслуживается карта. Рекомендуем повторить оплату через 2 минуты. |
| 55-unmatched_error | Помилка не визначена | Платіж відхилено Банком. Рекомендуємо звернутись на гарячу лінію, щоб уточнити у оператора причину відмови. | Платеж отклонен Банком. Рекомендуем обратиться на горячую линию, чтобы уточнить у оператора причину отказа. |
| 56-expired_card | Карта прострочена або невірно вказано термін дії | Платіж відхилений Банком, в якому у Вас обслуговується карта. Можливо, карта просточена або невірно вказано термін дії карти. Перевірте строк дії картки і повторіть операцію. | Платеж отклонен Банком, в котором у Вас обслуживается карта. Возможно, карта просточена или неверно указан срок действия карты. Проверьте срок действия карты и повторите операцию. |
| 57-invalid_card | Введено невірний номер карти, або карта в неприпустимому стані. | Платіж відхилено Банком, в якому у Вас обслуговується карта. Можливо, на карті спрацювали обмеження або ліміти на інтернет- операції. Рекомендуємо звернутись на гарячу лінію Вашого банку, щоб уточнити у оператора причину відмови. | Платеж отклонен Банком, в котором у Вас обслуживается карта. Возможно, на карте сработали ограничения либо лимиты на интернет- операции. Рекомендуем обратиться на горячую линию Вашего банка, чтобы уточнить у оператора причину отказа. |
| 58-card_limits_failed | Перевищено ліміт по карті | Платіж відхилено Банком, в якому у Вас обслуговується карта. Можливо, на карті спрацювали ліміти на інтернет- операції. Рекомендуємо звернутись на гарячу лінію Вашого банку, щоб уточнити у оператора причину відмови. | Платеж отклонен Банком, в котором у Вас обслуживается карта. Возможно, на карте сработали лимиты на интернет- операции. Рекомендуем обратиться на горячую линию Вашего банка, чтобы уточнить у оператора причину отказа. |
| 59-invalid_amount | Неправильна сума | Платіж відхилено Банком, в якому у Вас обслуговується карта. Рекомендуємо звернутись на гарячу лінію Вашого банку, щоб уточнити у оператора причину відмови. | Платеж отклонен Банком, в котором обслуживается Ваша карта. Рекомендуем обратиться на горячую линию Вашего банка, чтобы уточнить у оператора причину отказа. |
| 60-3ds_fail | Неможливо виконати 3DS транзакцію | Платіж відхилено. Так як, у момент оплати не було зв’язку з Банком у якому у Вас обслуговується карта. Рекомендуємо повторити оплату через 2 хвилини. | Платеж отклонен, так как, в момент оплаты не было связи с Банком или неверно указан одноразовый пароль, в котором у Вас обслуживается карта. Рекомендуем повторить оплату через 2 минуты. |
| 61-call_issuer | Зателефонуйте емітенту карти | Платіж відхилено Банком, в якому у Вас обслуговується карта. Рекомендуємо звернутись на гарячу лінію Вашого банку, щоб уточнити у оператора причину відмови. | Платеж отклонен Банком, в котором обслуживается Ваша карта. Рекомендуем обратиться на горячую линию Вашего банка, чтобы уточнить у оператора причину отказа. |
| 62-card_lost_or_stolen | Карта втрачена або вкрадена | Платіж відхилено Банком, в якому у Вас обслуговується карта. Рекомендуємо звернутись на гарячу лінію Вашого банку, щоб уточнити у оператора причину відмови. | Платеж отклонен Банком, в котором обслуживается Ваша карта. Рекомендуем обратиться на горячую линию Вашего банка, чтобы уточнить у оператора причину отказа. |
| Дата | Версія | Опис змін |
|---|---|---|
| 2019-12-01 | 1.0 | Додано запити для проведення платежів |
| 2020-01-30 | 1.0.1 | Додано обробку необов'язкового поля info у запросі CreateToken |
| 2020-02-28 | 1.0.2 | Додано запит GetTokenList Додано запит GetPaymentStatus До запитів CreateToken та PaymentCreate додано обробку info для зв'язування токенів |
| 2020-03-11 | 1.0.3 | Додано запит DeleteToken |
| 2020-04-01 | 1.0.4 | Додано коди відмови по операції A2CPay |
| 2020-04-14 | 1.0.5 | Додано запит "Створити токен (Перевірка 3DS)" |
| 2020-08-13 | 1.0.6 | Додані опціональні поля info, sender, receiver до запиту A2CPay |
| 2020-12-03 | 1.0.7 | У запити CreateToken, CreateToken3DS, PaymentCreate додані додаткові поля info в секцію cvd (Card Verification Data) |
| 2020-12-21 | 1.0.8 | Додано запит A2CBalance (A2C баланс мерчанта) |
| 2021-02-08 | 1.0.9 | Додано запит GetCardholderName (Отримати дані про власника карти) |
| 2021-02-08 | 1.1.0 | При створені платежу додана можливість працювати з предавторизацією платежу Додано запит Completion - дозволяє завершити платіж з статусом "предавторизація" |
| 2021-10-09 | 1.2.0 | Додано запит "Завершити платіж з транзікціями (Completion)" Додано запит "Reversal (Відмінити авторизацію)" |
| 2022-08-23 | 1.2.1 | У відповідь на Debiting додано код помилки, якщо списання неуспішне Додано приклад відповіді у випадку неуспіху запиту Debiting |
| 2023-07-05 | 1.22 |
- Додано поле transactions в запит Debiting. - Додана можливість вказувати версію API в запиті Debiting. - Додано поле ext_id в запит GetPaymentStatus для пошуку платежу. |
| 2023-08-07 | 1.23 |
- Додано можливість передачі версії в заголовках - Додано error_code у відповідях з помилкою |
| 2023-09-11 | 1.24 | - Додано метод Declare |
| 2023-12-14 | 1.25 |
- Додана можливість створення токенів mcts/vts за допомогою поля info.additional_tokens.mcts_vts - Додана можливість видалення токенів mcts/vts за допомогою методу DeleteToken вказавши тип токену - Додана можливість використовувати токени mcts/vts при створенні платежу вказавши тип токену (payment.card.token_type) - В методі GetTokenList тепер виводяться токени mcts/vts разом з tokly - Тепер в Debiting можна використовувати також токени mcts/vts вказавши тип токену - Додано метод GetCryptogram (Отримання криптограми по токену) - Тепер необхідно обов'язково передавати версію API в заголовках запиту |
| 2023-12-22 | 1.26 | - Додано поля отримувача в aml |
| 2024-01-04 | 1.27 | - Додано метод A2CInvoice для отримання довідок A2C платежів |
| 2024-01-04 | 1.28 | - Розширено інформацію, яку повертає GetTokenList |
| 2024-01-04 | 1.29 | - Додано можливість відміняти/повертати конкретну(і) транзакцію |
| 2024-01-04 | 1.30 | - Додано можливість Відправляти ext_id в PaymentCreate |
| 2024-01-04 | 1.31 | - Додано можливість отримувати terminal_id у відповіді на Debiting, Declare, Completion |
| 2024-06-28 | 1.32 | - Додано можливість отримувати rrn, auth_code, bank_acquirer_name, card_mask у відповіді на Debiting, Declare, Completion |
| 2024-07-18 | 1.33 | - Додано можливість вказувати дозволений тип карти для операцій (параметр allowed_card_types) |