Tokly API v1.32

Загальна інформація

Даний сервіс дозволяє створювати платежі, та віддавати посилання клієнтам на виконання списання коштів на користь мерчату.

Версія Апі

Обов'язково

Версія апі, яку ви використовуєте передається в заголовку з назвою Api-Version. Поточну версію, а також зміни в попередніх можна подивитись в Історії змін

    Api-Version: 1.32

Доступи й налаштування

Для взаємодії слід отримати наступні значенння:

- mch_id - ідентифікатор мерчанта
- sign_key - ключ мерчанта для підпису

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

Алгоритм підпису (поле sign у запиті):

Робиться у 2 етапи:

1. Сіль: Потрібно сформувати мітку часу Unix (1561559732.3642) та згенерувати хєш цієї мітки
Приклад на PHP:
$salt = sha1(microtime(true));
2. Підпис: Згенерувати хеш-код на основі ключа для підпису та солі, використовуючи метод HMAC і алгоритм хешування SHA-512
Приклад на PHP:
$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;

Результатом кодування має бути строка у виді:

omhlJHD00QZk32WstDHpAOGHV+bkud62nXI=.cyDAn2Q4QA2L++sICPciVw==
Приклад реалізації метода кодування на PHP:
     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 середовище

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

Для запиту A2CPay необхідно використовувати наведені нижче карти

Для успіху - 3333333333333331

Для неуспіху(з випадковим кодом помилки) - 3333333333333349

Для помилки "insufficient_balance" - 3333333333334552

Будь-який інший валідний номер карти призведе до помилки "invalid sandbox pan"

Перелік запитів

  1. CreateToken (Створити токен)

  2. Запит виконується на 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":{
            "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"
                }
            }
                    
  3. CreateToken3DS (Створити токен з 3DS перевіркою)

  4. Запит виконується на 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":{
            "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"
                }
            }
        
  5. Створити платіж (Операція списання на користь торговця)

  6. Після створення платежу у відповідь повертається 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.

    Приклад запиту

    
    
    <?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>
    
            
  7. Completion (Завершити платіж)

  8. Запит виконується на 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"
        }
    
    }
    
        
  9. Завершити платіж з транзікціями (Completion)

  10. Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST

    Запит викониється лише тоді, коли мерчант працює з предавторизацією платежа та потребує змін по розрахунку з юр.особами
    або потрібно завершити транзакцію з іншою сумою

    Принцип роботи Completion з транзакціями:

    На першому кроці створюється платіж за допомогою запросу 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"
        }
    
    }
    
        
  11. Заявити платіж в платіжну систему (Declare)

  12. Запит виконується на 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"
      }
    }
    
  13. Reversal (відміна операції/повернення платежу)

  14. Запит може бути виконано лише для успішного платежу.

    Доступні статуси:
    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"
        }
    
    }
            
  15. A2CPay (A2C оплата - операція виплати на картку клієнта)

  16. Запит виконується на 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"
                }
            }
            
  17. A2CPaymenStatus (A2C статус оплати)

  18. Запит виконується на 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"
                }
            }
            
  19. A2CBalance (A2C баланс мерчанта)

  20. Запит виконується на 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"
          }
        }
    
  21. A2CInvoice (Отримання довідки по A2C операціям)

  22. Запит виконується на 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"
    
  23. Debiting (Списання на користь торговця без участі картхолдера)

  24. Списання коштів на користь мерчанта без участі картхолдера

    Запит виконується на 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"
              }
            }
        
  25. GetTokenList (Отримати список токенів)

  26. Отримання списку токенов з прив'язкою до даних користувача

    Запит виконується на 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..."
                }
    
            }
            
  27. GetPaymentStatus (Отримати статус платежа)

  28. Отримання статусу платежу який здійснено мерчантом

    Запит виконується на 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..."
                }
            }
            
  29. DeleteToken (Видалити токен)

  30. Видалення токена запобігає створювання та оплат за данним токеном.
    Видалений токен можливо створити повторно

    Запит виконується на 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"
                }
    
            }
            
  31. GetCardholderName (Отримати дані про власника карти)

  32. Отримання даних про власника карти доступно лише для карт Приватбанку, Монобанку та ПУМБ

    Запит виконується на 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"
              }
            }
            
    2023 7ace5bc9a02a5af61efecd722b7b05e84d106c2a a112c1c344846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393 reversal 12345678

    Структура відповіді

    Поле Тип Опис
    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>
            
  33. GetReceipt (Чек платежу)

  34. Отримання чеку платежу

    Файл чеку буде отримано у відповіді на запит

    Структура тіла запиту

    Поле Тип Опис
    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"
                    }
                  }
                }
            
  35. GetCryptogram (Отримати криптограму)

  36. Запит виконується на https://tokly.ipay.ua/api у форматі JSON методом POST

    Структура тіла запиту

    "environment": "sandbox",
    Поле Тип Опис
    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"
              }
            }
            
  37. Нотифікація платежів

  38. Посилання або e-mail для нотифікації прописується на стороні iPay.ua і може бути доданий або змінений в будь-який час за заявкою відповідального співробітника.

    Нотифікації можуть бути наступних видів:

    1) web - дані відправляються на вказані вами посилання і містять повну, розгорнуту інформацію про платіж і його стані.
    Формат даних в цьому випадку - XML, дані будуть передані методом POST через поле xml, в якому буде міститися сповіщення.
    2) e-mail - дані будуть відправлені на вказані вами адреси електронної пошти. Формат даних в цьому випадку може бути XML або Plain.

    Всі нотифікації відправляються, як тільки операція з платником буде завершена. Уразі якщо, з якоїсь причини, 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>
    
            
  39. Помилки

  40. Опис помилки повертається у текстовому форматі в полі response.error

    Починаючи з версії 1.23, у відповіді також повертається error_code, а http-статус може бути відмінним від 200 або 500.

    Приклад відповіді:

            
                {
                    "response":{
                        "error":"missing required field desc",
                        "error_code":"U0"
                    }
                }
            
        

    Список можливих помилок(error_code=U0 http-статус=200 можуть бути змінені в майбутньому для певних помилок):

    Текст помилки Код помилки 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 заборонена
  41. Код відмови по операції для запросу A2CPay

  42. 
    
            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 - карта получателя заблокирована банком эмитентом
    
            
  43. Статуси платежу

  44. Значення поля status Опис
    1 Зареєстрований (в обробці)
    3 Пред-авторизований. Платіж очікує завершення методом Completion.
    4 Неуспішний
    5 Успішний
    9 Відмінений
    11 Ручна обробка
    13 Успішний платіж без заявлення в платіжну систему
    14 Відмова системи безпеки
  45. Код відмови по операціям для запитів CreateToken, CreateToken3DS, PaymentCreate, Debiting

  46. Код помилки Причина Повідомлення користувачу (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