Tokly API v1.2.0

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

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

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

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

- 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

Для неуспіху - 3333333333333349

Для предавторізації(де це можливо) - 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 Інформація до платежу, надається мерчантом. Повертається мерчанту в нотифікації
    Додаткові поля 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":{
            "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 Інформація до платежу, надається мерчантом. Повертається мерчанту в нотифікації
    Додаткові поля 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":{
            "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.transactions.transaction.smch_id integer Юридична особа, на користь якої здіюйснюється операція
    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 Отчество

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

    
    
    <?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>ru</lang>
    </payment>
    
                

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

    Поле Тип Опис
    payment element Початковий елемент
    payment.pid integer ID платежу в системі iPay
    payment.status integer Статус платежу (1 - зареєстрований, 3 - авторизований, 4 - неуспішний, 5 - успішний)
    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 Статус платежу (1 - зареєстрований, 3 - авторизований, 4 - неуспішний, 5 - успішний)
    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-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 Статус платежу (1 - зареєстрований, 3 - авторизований, 4 - неуспішний, 5 - успішний)
    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. Reversal (відміна операції/повернення платежу)

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

    Доступні статуси: 3(авторизовано) - лише для мерчантів, які працюють з предавторизацією; 5(успішний) - для доступу до повернень у день відмінний від дня платежу, звертайтесь у підримку;

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

    Поле Тип Опис
    payment element Початковий елемент
    payment.auth element Елемент аутентифікації
    payment.auth.mch_id numeric ID мерчанта
    payment.auth.salt string Сіль підпису
    payment.auth.sign string Підпис запиту
    payment.action string Назва запиту
    payment.pid numeric ID платежу в системі iPay

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

    
    
    {
    
        "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 Статус платежу (3 - авторизований, 9 - скасований)
    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"
        }
    
    }
            
  13. A2CPay (A2C оплата - операція виплати на картку клієнта)

  14. Запит виконується на 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.receiver element Початковий элемент одержувача
    request.body.receiver.lastname string Прізвище одержувача
    request.body.receiver.firstname string Ім'я одержувача
    request.body.receiver.middlename string По батькові одержувача
    request.body.receiver.address string Адреса одержувача (наприклад: Київ, вул. Тестова, 10)

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

    
    {
    
        "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 Статус платежу (1 - в обробці, 4 - неуспішний, 5 - успішний)
    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"
                }
            }
            
  15. A2CPaymenStatus (A2C статус оплати)

  16. Запит виконується на 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 Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний)
    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. A2CBalance (A2C баланс мерчанта)

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

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

    Запит виконується на 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.invoice integer сумма у копійках
    request.body.desc string Опис платежу
    request.body.info json object Інформація до платежу, надається мерчантом при створенні
    request.body.card element Елемент картки
    request.body.card.token string Токен карти

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

    
    
            {
                "request":{
                    "auth":{
                        "mch_id":2023,
                        "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9",
                        "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2"
                    },
                    "action":"Debiting",
                    "body":{
                        "invoice":20,
                        "desc":"test",
                        "info":"[]",
                        "card":{
                            "token": "MWNiNTE3...zNWNhMzFjNzAw"
                        }
                    }
                }
            }
    
            

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

    Поле Тип Опис
    response element Початковий елемент
    response.pmt_id integer ID платежу в системі iPay
    response.bnk_error_note string Код помилки. Пояснення кодів описано тут
    response.status integer Статус платежу (3 - авторизований, 4 - неуспішний, 5 - успішний)
    response.invoice integer Сума платежу, у копійках
    response.amount integer Сума до сплати (з урахуванням комісії), у копійках
    response.salt string Сіль підпису
    response.sign string Підпис запиту

    Приклад відповіді у випадку успішного списання

    
            {
                "response":{
                    "pmt_id":44482724,
                    "status":5,
                    "invoice":100,
                    "amount":100,
                    "salt":"5e955d067cd3aebfb7ad2f4aa7f69c51b902a7e9",
                    "sign":"0ef8d7588d9b91a1a48de9ca241bc60b6f286890ae58cef452c0b6ef52d1fd72d5f61c4695039c4512caffda945d77496fdb98e766ba69b0a1624d7a13687cd2"
                }
            }
            

    Приклад відповіді у випадку неуспіху

    
            {
              "response": {
                "pmt_id": 162136260,
                "status": 4,
                "bnk_error_note": "42-insufficient_funds",
                "amount": 200000,
                "invoice": 200000,
                "salt": "e6c468877d50c07fea027b2708a57fc36fa56d0f",
                "sign": "708cad33a5db5626a11bb4300349a9bf0989718e7d6d336ccdab5516eb3d1350b7ad1fb1493569948650e19a5a1b061eca9f9ebf021d2c0efb"
              }
            }
        
  21. GetTokenList (Отримати список токенів)

  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 element Тіло запиту
    request.body.bind string Значення з котрим було зв'язано токен

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

    
    
            {
    
                "request":{
                    "auth":{
                        "mch_id":2023,
                        "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9",
                        "sign":"5c11fd7ba12a4d5eb7da121bc04d360a5c11fd7b..."
                    },
                    "action":"GetTokenList",
                    "body":{
                        "bind":"987654987654ABC"
                    }
                }
    
            }
    
            

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

    Поле Тип Опис
    response element Початковий елемент
    response.bind string Значення з яким пов'язаний токен
    response.TokenList element Массив токенів
    response.salt string Сіль підпису
    response.sign string Підпис запиту

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

    
            {
    
                "response":{
                    "bind":"987654987654ABC",
                    "TokenList":[
                        {
                            "token":"A2FjYjg2ZmJiMGJlYjc3MjVhZDU4OGIwYjkzNjc2ZmFmMzlhNWZkMmJmOWVjZWM4MTY2YWMzZTM0YjVfNDJiYjAw",
                            "card_mask":"123456******7890",
                            "active":0
                        },
                        {
                            "token":"AjczOWJhYUIxYTg4YzljCTQ4MjllOZdlOTI2NTZhMjI3OWYwMTBmZGU3ZGJjZDUzMWVjYTEwYjg1ZGM1ZjJlNTAw",
                            "card_mask":"654321******7890",
                            "active":1
                        },
                        {
                            "token":"Ajc2NGUzY2MxMTkwMWZmYjdhMjdlZWYyMzE0MTU6NDkxMDhjYmEwYTlmMWE5OTgzM2RkMjhjYmFaOTZmMDc3NjAw",
                            "card_mask":"123456******0987",
                            "active":1
                        }
                    ],
                    "salt":"2e6a36e370ddc3c6f25c80c111a9e86428533fdd",
                    "sign":"b7579f34db23de5446d899d8f2985c9cb001f727..."
                }
    
            }
            
  23. GetPaymentStatus (Отримати статус платежа)

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

    Запит виконується на 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":{
                    "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.status integer Статус платежу (1 - платіж зареєстровано, 4 - неуспішний, 5 - успішний, 9 - відмінено)
    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.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..."
                }
            }
            
  25. DeleteToken (Видалити токен)

  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.token integer Токен карти

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

    
    
            {
    
                "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"
                }
    
            }
            
  27. GetCardholderName (Отримати дані про власника карти)

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

    Запит виконується на 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 Статус платежу ( 9 - скасований)
    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>
            
    -->
  29. Нотифікація платежів

  30. Посилання або 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 Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний)
    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.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>
    
            
  31. Помилки

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

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

            
                {
                    "response":{
                        "error":"missing required field \"desc\""
                    }
                }
            
        

    Список можливих помилок:

    Текст помилки Причина
    missing required field "desc" Не передане обов'язкове поле desc у запиті
    overall error Загальна помилка, за більш детальною інформацією звертатися до iPay
    Помилки запиту Reversal
    not enough turnover Недостатньо обороту за день
    not enough turnover Недостатньо обороту за день
    not enough turnover Недостатньо обороту за день
    no balance Недостатньо коштів на балансі
    no deposit for refund Не знайдено депозит, за більш детальною інформацією звертайтеся до iPay
    reversal amount must be fewer than payment invoice Якщо за договором зовнішня комісія не повертається, то при частковому поверненні сума повернення повинна бути меншою ніж інвойс платежу
  33. Код відмови по операції для запросу A2CPay

  34. 
    
            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 - карта получателя заблокирована банком эмитентом
    
            
  35. Код відмови по операціям для запитів CreateToken, CreateToken3DS, PaymentCreate, Debiting

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