Tokly API v1.0.5

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

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

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

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

- 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 в якому містится ключ та значення

{"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:
private function encryptData($raw_data = NULL, $key = NULL){
        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;
    }

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

  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 сторінках
    Опціональні поля
    request.body.cdata string Закодовані картданні
    request.body.url_good string Посилання до сторінки успіху мерчанта
    request.body.url_bad string Посилання до сторінки неуспіху мерчанта
    request.body.info json Інформація до платежу, надається мерчантом. Повертається мерчанту в нотифікації

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

    
    
            {
    
                "request":{
                    "auth":{
                        "mch_id":2023,
                        "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9",
                        "sign":"a12a4d5eb7da121bc04d360a5c11fd7b"
                    },
                    "action":"CreateToken",
                    "body":{
                        "cdata":"omhlJHD00QZk32WstDHpAOGHV+bkud62nXI=.cyDAn2Q4QA2L++sICPciVw==",
                        "info":{
                                "order_id":112233,
                                "ext_id":12345,
                                "user_id":54321,
    
                        }
    
                    },
                    "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 сторінках
    Опціональні поля
    request.body.cdata string Закодовані картданні
    request.body.url_good string Посилання до сторінки успіху мерчанта
    request.body.url_bad string Посилання до сторінки неуспіху мерчанта
    request.body.info json Інформація до платежу, надається мерчантом. Повертається мерчанту в нотифікації

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

    
    
            {
                "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
                        }
                    },
                    "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 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 integer Термін можливості зробити оплату, вимірюється у годинах
    payment.lang string Мова яку буде відображено на WEB сторінках
    Опціональні поля
    payment.transactions.transaction.smch_id integer Юридична особа, на користь якої здіюйснюється операція
    payment.card.token string Токен карти
    payment.card.cdata 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}</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 - зареєстрований, 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>e9be5bc9a02a5af61efecd722b7b05e84d106d1a</salt>
        <sign>0c8698119b846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393</sign>
        <url>https://tokly.ipay.ua/a1f7e6a6ced6fc72d4dbb48da6babc7d2ca89ac2</url>
    </payment>
    
            
  7. A2CPay (A2C оплата - операція виплати на картку клієнта)

  8. Запит виконується на 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 Унікальний ідентифікатор оплати в системній мерчанта
    request.body.card element Елемент картки
    request.body.card.pan string пан карти
    request.body.card.token string токен карти

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

    
    
            {
    
                "request":{
                    "auth":{
                        "mch_id":2023,
                        "salt":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9",
                        "sign":"a12a4d5eb7da121bc04d360a5c11fd7b"
                    },
                    "action":"A2CPay",
                    "body":{
                        "invoice": 100,
                        "ext_id": "1234567890ABCD",
                        "card":{
                            "pan": "1234567890123456",
                            "token": "MWNiNTE3...zNWNhMzFjNzAw"
                        }
                    }
                }
            }
    
            

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

    Поле Тип Опис
    response element Початковий елемент
    response.pmt_id integer ID платежу в системі iPay
    response.status integer Статус платежу (4 - неуспішний, 5 - успішний)
    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"
                }
            }
            
  9. A2CPaymenStatus (A2C статус оплати)

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

    Запит повинен містити у структурі одночасно лише ext_id або pmt_id

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

    Поле Тип Опис
    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.amount integer сумма у копійках
    request.body.ext_id string Унікальний ідентифікатор оплати в системній мерчанта
    Опціональні поля
    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 Статус платежу (4 - неуспішний, 5 - успішний)
    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"
                }
            }
            
  11. Debiting (Списання на користь торговця без участі картхолдера)

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

    Запит виконується на 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.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.status integer Статус платежу (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":"5eb902aad2f4aa7f7955d067cdb769c53aebf1e9",
                    "sign":"0ef8d7588d9b91a141bc60bf452c0b6ef52d1fd72d5f61c4695039c4512ca945d77496fd6f286890ae58ceb98e766ba69b0a1624d7aaffd1368a48de9ca27cd2"
                }
            }
            
  13. GetTokenList (Отримати список токенів)

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

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

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

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

  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.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"
                }
    
            }
            
  19. Нотифікація платежів

  20. Посилання або 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 Підпис запиту

    Приклад нотифікації

    
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <payment id="12345678">
    	<ident>2b45db39f12555f3ef5dd129eea28d70c5a33ffc</ident>
    	<status>5</status>
    	<amount>110</amount>
    	<currency>UAH</currency>
    	<timestamp>1562660681</timestamp>
        <card_token>MWNiNTE3...zNWNhMzFjNzAw</card_token>
    	<transactions>
    		<transaction id="4567890">
    			<mch_id>1234</mch_id>
    			<smch_id>4301</smch_id>
    			<invoice>100</invoice>
    			<amount>110</amount>
    			<desc>Покупка услуги/товара</desc>
    			<info>{"dogovor":12345}</info>
    		</transaction>
    	</transactions>
    	<salt>f7be5bf13c644264df5757314946c6464627c7af</salt>
    	<sign>23fd4c70bebe99549b4d9b078e2ddd69a5bdcce684c1a663eeb1036fd0d8c760408bb281df755228bc8d09ad93ec53b7516e01bbe0d39c27c4253d113156201a</sign>
    </payment>
    
            
  21. Помилки

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

    Наприклад: не передане обов'язкове поле desc у запросі

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

    Загальна помилка, за більш детальною інформацією звертатися до iPay

    
            {
                "response":{
                    "error":"overall error"
                }
            }
            
  23. Код відмови по операції для запросу A2CPay

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

Історія змін

Дата Версія Опис змін
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)"