Tokly API v1.2.0

Загальна інформація
Доступи й налаштування
Кодування карткових данних
Sandbox середовище
Перелік запитів
Помилки
Код відмови по операції для запиту A2CPay
Код відмови по операціям для запитів CreateToken, CreateToken3DS, Створити платіж
Історія змін

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

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

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

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

- 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
3333333333333000
3333333333333703
3333333333332820
3333333333333430
3333333333331509

Для неуспіху:
3333333333333349
3333333333336409
3333333333339205
3333333333338710
3333333333337605
3333333333337340
3333333333339403
3333333333337720
3333333333335120
3333333333335930

Для предавторізації(де це можливо) - 3333333333333356

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

Для успіху - 3333333333333331

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

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

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

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

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

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

CreateToken3DS (Створити токен з 3DS перевіркою)

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

Створити платіж (Операція списання на користь торговця)

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

Completion (Завершити платіж)

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

}

Завершити платіж з транзікціями (Completion)

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

}

Reversal (відміна операції/повернення платежу)

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

Доступні статуси: 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"
    }

}

A2CPay (A2C оплата - операція виплати на картку клієнта)

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

A2CPaymenStatus (A2C статус оплати)

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

A2CBalance (A2C баланс мерчанта)

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

Debiting (Списання на користь торговця без участі картхолдера)

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

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

GetTokenList (Отримати список токенів)

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

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

        }

GetPaymentStatus (Отримати статус платежа)

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

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

DeleteToken (Видалити токен)

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

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

        }

GetCardholderName (Отримати дані про власника карти)

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

Запит виконується на 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>

Нотифікація платежів

Посилання або 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>

Помилки

Опис помилки повертається у текстовому форматі в полі 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	Якщо за договором зовнішня комісія не повертається, то при частковому поверненні сума повернення повинна бути меншою ніж інвойс платежу

Код відмови по операції для запросу A2CPay



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

Код відмови по операціям для запитів CreateToken, CreateToken3DS, PaymentCreate, Debiting

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

Tokly API v1.2.0

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

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

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

Кодування карткових данних

Sandbox середовище

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

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

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

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

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

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

CreateToken3DS (Створити токен з 3DS перевіркою)

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

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

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

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

Створити платіж (Операція списання на користь торговця)

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

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

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

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

Completion (Завершити платіж)

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

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

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

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

Завершити платіж з транзікціями (Completion)

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

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

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

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

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

Reversal (відміна операції/повернення платежу)

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

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

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

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

A2CPay (A2C оплата - операція виплати на картку клієнта)

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

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

Структура опціональних полей з реквізитами Відправника і Одержувача

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

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

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

A2CPaymenStatus (A2C статус оплати)

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

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

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

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

A2CBalance (A2C баланс мерчанта)

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

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

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

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

Debiting (Списання на користь торговця без участі картхолдера)

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

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

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

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

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

GetTokenList (Отримати список токенів)

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

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

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

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

GetPaymentStatus (Отримати статус платежа)

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

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

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

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

DeleteToken (Видалити токен)

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

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

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

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

GetCardholderName (Отримати дані про власника карти)

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

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

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