Checkout API v1.11

Загальна інформація
Доступи й налаштування
Sandbox середовище
Загальна структура запиту
Перелік запитів
Історія змін

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

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

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

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

- mch_id - ідентифікатор мерчанта

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

URL адреса для запитів - https://checkout.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://checkout.ipay.ua/api302' -data 'data= ...

Кодування у 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);

Sandbox середовище

Sandbox - тестове середовище, з допомогою якого можна виконати:

тестування запитів, тестування web інтерфейсу, провести тестову оплату, виконати тестове скасування

Посилання для подання запиту на формування платежу https://sandbox-checkout.ipay.ua/api302

Функціонал повторює продакшн середу по поточній документації Checkout API

У Sandbox не працює і відключена оплата GPay, ApplePay, VCO тощо - тому що там тільки продакшн середовище

Для web тестування оплат необхідно використовувати наведені нижче карти, з будь-якою датою та CVV

Карти для яких завжди буде успіх, незалежно від суми:
3333333333333331
3333333333332705
3333333333333000
5375913862726080

Карти для яких успіх буде при сумі до 100 грн, платежі з більшою сумою будуть давати неуспіх:
3333333333333430
3333333333331509
5375912476960515
5117962099480048
4005520000000129
4164978855760477

Карти для яких успіх буде при сумі до 100 грн, платежі з більшою сумою будуть давати предавторизацію:
3333333333479407
3333333333334503
5117963095204135
4341500505113562

Для неуспіху, незалежно від суми:
3333333333333349
3333333333336409
3333333333339205
4280596505234682
5218572540397762

Для предавторизації, незалежно від суми:
3333333333333356

Загальна структура запиту

Поле	Тип	Опис
payment	element	Початковий Елемент
payment.auth	element	Елемент аутентифікації
payment.auth.mch_id	numeric	ID мерчанта
payment.auth.salt	string	Сіль підпису
payment.auth.sign	string	Підпис запиту
payment.urls	element	Елемент посилань
payment.transactions	element	Елемент транзакцій
payment.transactions.transaction	element	Елемент
payment.lifetime	float	Термін можливості зробити оплату, вимірюється у годинах(3600 секунд). Може бути дробовим. У випадку значення 0.1, термін життя посилання 6 хвилин(360 секунд)
payment.lang	string	Мова яку буде відображено на WEB сторінках

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



<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment>
    <auth>
        <mch_id>2023</mch_id>
        <salt>c2cbe9bbbce5c6870475b7c649da8205c30ffe65</salt>
        <sign>2b99f7b6a8ea065f6a28bc86eb2de84bffb2b887a2a9c9dbee5818b46f96e093cc397a2755f8663a745672bdf654e20e001853e1f780f3a3fa23ee9189046fac</sign>
    </auth>
    <urls>
        ...
    </urls>
    <transactions>
        ...
    </transactions>
    <lifetime>24</lifetime>
    <lang>ru</lang>
</payment>

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

PaymentCreate (Створити платіж)

Після створення платежу у відповідь повертається URL, по якому клієнт робить оплату послуги/товару

так-як оплата клієнтом здійснюється безпосередньої участі мерчанта, на стороні checkout.ipay.ua, то мерчанту по завершенню
оплати приходить нотифікація

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

Поле	Тип	Опис
payment	element	Початковий елемент
payment.auth	element	Елемент аутентифікації
payment.auth.mch_id	numeric	ID мерчанта
payment.auth.salt	string	Сіль підпису
payment.auth.sign	string	Підпис запиту
payment.urls	element	Елемент посилань
payment.urls.good	string	Посилання до сторінки успіху мерчанта
payment.urls.bad	string	Посилання до сторінки неуспіху мерчанта
payment.urls.auto_redirect_good	bool	Чи потрібно робити автоматичний редірект на payment.urls.good (0 - ні, 1 - так)
payment.urls.auto_redirect_bad	bool	Чи потрібно робити автоматичний редірект на payment.urls.bad (0 - ні, 1 - так)
payment.transactions	element	Елемент транзакцій
payment.transactions.transaction	element	Елемент транзакції. Якщо платіж потрібно розділити на кілька юридичних осіб, можна відправити кілька елементів транзакції (максимум 10) з указаними amount та smch_id у кожному .
payment.transactions.transaction.amount	numeric	Сумма у копійках
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 сторінках
Опціональні поля
payment.transactions.transaction.smch_id	numeric	Юридична особа, на користь якої здіюйснюється операція
payment.trademark	json object	Назва компанії, яку хоче відобразити мерчант
payment.transactions.transaction.info.aml.sender_fio	string	Повне ім'я відправника. Може передаватись замість окремої передачі в sender_firstname, sender_middlename, sender_lastname
payment.transactions.transaction.info.aml.sender_firstname	string	Ім'я відправника
payment.transactions.transaction.info.aml.sender_middlename	string	По-батькові відправника
payment.transactions.transaction.info.aml.sender_lastname	string	Прізвище відправника
payment.transactions.transaction.info.aml.sender_identification_number	string	ІПН (Індивідуальний податковий номер) / Код ЄДРПОУ (Єдиного державного реєстру підприємств та організацій України) відправника
payment.transactions.transaction.info.aml.sender_document	string	Номер документа відправника
payment.transactions.transaction.info.aml.sender_address	string	Адреса відправника
payment.transactions.transaction.info.aml.sender_account_number	string	Розрахунковий рахунок відправника

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



<?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>
        <auto_redirect_good>1</auto_redirect_good>
        <auto_redirect_bad>1</auto_redirect_bad>
    </urls>
    <transactions>
        <transaction>
            <amount>55</amount>
            <currency>UAH</currency>
            <desc>Покупка товара/услуги</desc>
            <info>{"dogovor":123456}</info>
            <smch_id>4301</smch_id>
        </transaction>
    </transactions>
    <trademark>{"ru":"название на русском","ua":"назва на українській","en":"english name"}</trademark>
    <lifetime>24</lifetime>
    <lang>ru</lang>
</payment>

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

Поле	Тип	Опис
payment	element	Початковий елемент
payment.pid	numeric	ID платежу в системі iPay
payment.status	string	Статус платежу (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>e9be5bc9a02a5af61efecd722b7b05e84d106d1a</salt>
    <sign>0c8698119b846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393</sign>
    <url>https://checkout.ipay.ua/a1f7e6a6ced6fc72d4dbb48da6babc7d2ca89ac2</url>
</payment>

PaymentCreateWithService (Створити платіж і виконати сервіс)

Для виконання сервісу потрібно в поле payment.transactions.transaction.info передати параметри service_data у json форматі

Після успішного списання, автоматично буде виконано сервіс

Якщо списання проводиться за допомогою запиту Completion з передачею транзакцій, параметр service_data повинен передаватись там, а не в PaymentCreate

Поле	Тип	Опис
Опціональні поля
payment.transactions.transaction.info.service_data	object	Параметри які передані мерчантом для виконання сервісу
service_data.Receiver	string	Отримувач
service_data.ZKPO	string	ЕДРПО
service_data.BankReciever	string	Назва банку
service_data.AccReceiver	string	IBAN
service_data.PayText	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://abvgd.s62.in.ua/complete-payment?key=20000202%26pin=8986</good>
      <bad>http://abvgd.s62.in.ua/failed-payment?key=7171717%26pin=898989</bad>
  </urls>
  <transactions>
      <transaction>
          <mch_id>2023</mch_id>
          <type>11</type>
          <amount>30</amount>
          <currency>UAH</currency>
          <desc>Платеж абонента Телезяк Оксана Богдановна договор 441304607</desc>
          <info>
              {
                  "OrderID": 193971,
                  "PersonID": 220263,
                  "service_data": {
                    "Receiver": "Товариство з обмеженою відповідальністю",
                    "ZKPO": "39708282",
                    "BankReciever": "АТ \"Райффайзен Банк Аваль\"",
                    "AccReceiver": "UA213808050000000026009479663",
                    "PayText": "Оплата по догляду за дитиною за місяць 2017р. від 123456 Сума 10 грн."
                  }
              }
          </info>
      </transaction>
  </transactions>
  <lifetime>24</lifetime>
  <trademark>{"ru":"название на русском","ua":"назва на українській","en":"english name"}</trademark>
  <lang>ru</lang>
</payment>

PaymentCreate (з транзакціями) WithService(Створити платіж і виконати сервіс з транзакціями)

Для виконання сервісу потрібно в поле payment.transactions.transaction.info передати параметри service_data у json форматі. Після успішного списання, автоматично буде виконано сервіс

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


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment>
  <auth>
    <mch_id>2023</mch_id>
    <salt>a197706e94bdcc4b6b1a583bafc06c9790088be3</salt>
    <sign>1dd8f152e042cf401fdf2c204746717425085ac14c99d30d2e05e23d764e2039557e9bd99bde55103f2709c344f746be23df99d652f303543e1e0ff633f7b14d</sign>
  </auth>
  <urls>
    <good>http://www.example.com/ok/</good>
    <bad>http:// www.example.com/fail</bad>
  </urls>
  <transactions>
    <transaction>
      <amount>100</amount>
      <currency>UAH</currency>
      <desc>Покупка товара/услуги</desc>
      <info>
        {
          "historyID": 1879,
          "company": 1111,
          "service_data": {
            "Receiver": "Товариство з обмеженою відповідальністю",
            "ZKPO": "39708282",
            "BankReciever": "АТ \"Райффайзен Банк Аваль\"",
            "AccReceiver": "UA213808050000000026009479663",
            "PayText": "Оплата по догляду за дитиною за місяць 2017р. від 123456 Сума 10 грн."
          }
        }
      </info>
      <smch_id>4301</smch_id>
    </transaction>
    <transaction>
      <amount>200</amount>
      <currency>UAH</currency>
      <desc>Покупка товара/услуги</desc>
      <info>
        {
          "historyID": 1111,
          "company": 2222,
          "service_data": {
            "Receiver": "Товариство з обмеженою відповідальністю",
            "ZKPO": "39708282",
            "BankReciever": "АТ \"Райффайзен Банк Аваль\"",
            "AccReceiver": "UA213808050000000026009479663",
            "PayText": "Оплата по догляду за дитиною за місяць 2017р. від 123456 Сума 10 грн."
          }
        }
      </info>
      <smch_id>4551</smch_id>
    </transaction>
  </transactions>
  <trademark>{"ru":"название на русском","ua":"назва на українській","en":"english name"}</trademark>
  <lifetime>24</lifetime>
  <lang>ru</lang>
</payment>

PaymentCreate з фіскальним чеком

Для створення фіскального чеку потрібно в поле payment.transactions.transaction.info передати параметри receipt_data у json форматі. Після успішного списання, автоматично буде згенеровано фіскальний чек, який можна буде отримати за допомогою запиту GetReceipt

Поле	Тип	Опис
Опціональні поля(обов'язкові для створення фіскального чеку)
payment.transactions.transaction.info.receipt_data	object	Інформація для фіскалізації платежу
receipt_data.cashier_id	integer	ID касира в системі iPay
receipt_data.cash_register_id	integer	ID каси в системі iPay
receipt_data.goods	array	Список товарів
receipt_data.goods[].id	string	ID товару в форматі UUID
receipt_data.goods[].code	string	Код товару
receipt_data.goods[].barcode	string	Штрих-код товару
receipt_data.goods[].price	integer	Вартість в копійках
receipt_data.goods[].quantity	integer	Кількість (наприклад: 1 шт = 1000, 2.25 кг = 2250)
receipt_data.discounts	array	Зчижка чи надбавка
receipt_data.discounts[].type	string	Тип знижки. Доступні значення: DISCOUNT (знижка), EXTRA_CHARGE (надбавка)
receipt_data.discounts[].mode	string	Режим знижки. Доступні значення: PERCENT (відсоткова знижка), VALUE (абсолютне значення)
receipt_data.discounts[].value	integer\|float	Значення знижки чи надбавки

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


<?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>
        <auto_redirect_good>1</auto_redirect_good>
        <auto_redirect_bad>1</auto_redirect_bad>
    </urls>
    <transactions>
        <transaction>
            <amount>55</amount>
            <currency>UAH</currency>
            <desc>Покупка товара/услуги</desc>
            <info>
                {
                    "receipt_data": {
                        "cashier_id": "1",
                        "cash_register_id": "1",
                        "goods": [
                            {
                                "id": "42d73b27-238a-48b1-90cb-308437dd1168",
                                "code": "Код товару 1",
                                "name": "Назва товару 1",
                                "price": "100",
                                "quantity": "1000"
                            },
                            {
                                "id": "67f30096-8df9-4538-9f98-587224abbc6b",
                                "code": "Код товару 2",
                                "name": "Назва товару 2",
                                "price": "400",
                                "quantity": "1000"
                            }
                        ]
                    }
                }
            </info>
            <smch_id>4301</smch_id>
        </transaction>
    </transactions>
    <trademark>{"ru":"название на русском","ua":"назва на українській","en":"english name"}</trademark>
    <lifetime>24</lifetime>
    <lang>ru</lang>
</payment>

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

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

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

Поле	Тип	Опис
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

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



<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment>
    <auth>
        <mch_id>2023</mch_id>
        <salt>7ace5bc9a02a5af61efecd722b7b05e84d106c2a</salt>
        <sign>a112c1c344846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393</sign>
    </auth>
    <action>completion</action>
    <pid>12345678</pid>
</payment>

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

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

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


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment>
    <pid>12345678</pid>
    <status>5</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>

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

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

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

На першому кроці створюється платіж за допомогою запросу PaymentCreate в якому повинна бути сформована одна транзакція
з загальною сумою оплати і юрособою самого мерчанта.

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

До цього моменту потрібно обов'язково подати запит на завершення оплати.

При формуванні транзакцій на завершення оплати (Completion) необхідно дотримуватися кількох правил:
1. Повинна бути сформована 1 або кілька транзакцій
2. Загальна сума транзакцій не повинна бути більше ніж при створенні платежу, інакше буде помилка.
Виправляти помилку слід шляхом подачі запиту з коректною сумою.
3. Якщо сума транзакцій буде менше, відбудеться часткова відміна по платежу і різниця повернеться на карту.
4. Для повної відміни, не в день сплати платежу, необхідно звертатися на пошту support@ipay.ua
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
payment.transactions	element	Елемент транзакцій
payment.transactions.transaction	element	Елемент транзакції (максимум 10)
payment.transactions.transaction.amount	numeric	Сумма у копійках
payment.transactions.transaction.currency	string	Валюта
payment.transactions.transaction.desc	string	Опис платежу
payment.transactions.transaction.info	json object	Інформація до платежу, надається мерчантом при створенні
payment.transactions.transaction.smch_id	numeric	Юридична особа, на користь якої здіюйснюється операція

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



<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment>
    <auth>
        <mch_id>2023</mch_id>
        <salt>b023c452f23cf71d71cb41ec494a1b9dd7dde476</salt>
        <sign>720fc5f843253f7b8bb6a0515afa27f3d89d6257b306827619df1e465838b36c56d77a6c8b9dd64fd7833e95b1740747bb65b89f44bcd731299f7c4f5693efe</sign>
    </auth>
    <action>completion</action>
    <pid>12345678</pid>
    <transactions>
        <transaction>
            <amount>100</amount>
            <currency>UAH</currency>
            <desc>Покупка товара/услуги</desc>
            <info>{"dogovor":12345}</info>
            <smch_id>4301</smch_id>
        </transaction>
        <transaction>
            <amount>200</amount>
            <currency>UAH</currency>
            <desc>Покупка услуги/товара</desc>
            <info>{"dogovor":56789}</info>
            <smch_id>4551</smch_id>
        </transaction>
    </transactions>
</payment>

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

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

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


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment>
    <pid>12345678</pid>
    <status>5</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>
        <transaction>
            <trn_id>55667788</trn_id>
            <smch_rr>26501014380602</smch_rr>
            <smch_mfo>300346</smch_mfo>
            <smch_okpo>37973023</smch_okpo>
            <smch_bank>ПАТ "АЛЬФА-БАНК"</smch_bank>
            <invoice>200</invoice>
            <amount>220</amount>
        </transaction>
    </transactions>
    <salt>a97688b38115a7b42f45ca75a2fe6f6fb536b57d</salt>
    <sign>566d16af0f9aeb32d055a2117160194ec0868ce418152a6ffb83a84037b4f28b9d345ee7f84a0374101771f891779ad013e26e3540c26f4734d8717097f39bc9</sign>
</payment>

Reversal (Відмінити авторизацію/платіж)

Відмінити авторизацію:

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

Запит може бути виконано лише за умови успішної предавторизації платежу,
та платіж знаходиться у статусі 3 - авторизований

Відмінити платіж:

Запит можно виконати лише у той-же день коли був сплачен платіж і лише на повну суму оплати,
тобто не було часткового повернення коштів на этапі оплати

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

Поле	Тип	Опис
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
payment.info	json object	Інформація до платежу, доповнює інформацію, яка була отримана при створені платежу

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



<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment>
    <auth>
        <mch_id>2023</mch_id>
        <salt>7ace5bc9a02a5af61efecd722b7b05e84d106c2a</salt>
        <sign>a112c1c344846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393</sign>
    </auth>
    <action>reversal</action>
    <info>{"reversal_id": "123456"}</info>
    <pid>12345678</pid>
</payment>

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

Поле	Тип	Опис
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	Підпис запиту

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


<?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>

Refund (Повернення коштів)

Виконати повернення коштів: доступ надається за згодою

Запит виконується у наступні дні після сплати платежу

Запит може бути виконано лише за умови успішної оплати платежу,
та платіж знаходиться у статусі 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
Опціональні поля
payment.amount	numeric	Сума часткового повернення, у копійках
payment.info	json object	Інформація до платежу, доповнює інформацію, яка була отримана при створені платежу

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



<?xml version="1.0" encoding="utf-8" standalone="yes"?><payment>
    <auth>
        <mch_id>2023</mch_id>
        <salt>7ace5bc9a02a5af61efecd722b7b05e84d106c2a</salt>
        <sign>a112c1c344846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393</sign>
    </auth>
    <action>refund</action>
    <info>{"refund_id": "123456"}</info>
    <pid>12345678</pid>
</payment>

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

Поле	Тип	Опис
payment	element	Початковий елемент
payment.pid	numeric	ID платежу в системі iPay
payment.status	string	Статус платежу (5 - успішний: при частковому поверненні, 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	Підпис запиту

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


<?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>

Status (Статус платежу)

Отримання статусу платежу

1 - платіж створений
4 - платіж неуспішний
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
Опціональні поля

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


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
        <payment>
            <auth>
                <mch_id>2023</mch_id>
                <salt>7ace5bc9a02a5af61efecd722b7b05e84d106c2a</salt>
                <sign>a112c1c344846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393</sign>
            </auth>
            <action>status</action>
            <pid>12345678</pid>
        </payment>

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

Поле	Тип	Опис
payment	element	Початковий елемент
payment.pmt_id	numeric	ID платежу в системі iPay
response.pmt.status	integer	Статус платежу (1 - платіж зареєстровано, 4 - неуспішний, 5 - успішний, 9 - відмінено)
payment.card_mask	string	Маскована карта
payment.invoice	integer	Сумма платежу без комісії
payment.amount	integer	Сумма платежу з комісією
payment.desc	string	Призначення платежу
payment.bnk_error_group	integer	Група помилки
payment.bnk_error_note	string	Текстове визначення помилки
payment.init_date	string	Дата створення платежу
payment.salt	string	Сіль підпису
payment.sign	string	Підпис запиту

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


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
         <payment>
            <salt>cc348f94880ed17b1b09e1061ff6984d88042cc8</salt>
            <sign>d11b748a790102fe36f6949eba2ad3aceb4e358c7cf54813384dfb71bef22b4037376ae6767af60ac9676280b89f27822acaaf376c1d27571f778c6859505502</sign>
            <pmt_id>12345678</pmt_id>
            <status>1</status>
            <card_mask>***</card_mask>
            <invoice>30</invoice>
            <amount>30</amount>
            <desc>test</desc>
            <init_date>2021-03-19 12:33:17</init_date>
            <bnk_error_group></bnk_error_group>
            <bnk_error_note></bnk_error_note>
        </payment>

GetReceipt (Чек платежу)

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

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

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

Поле	Тип	Опис
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

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


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
        <payment>
            <auth>
                <mch_id>2023</mch_id>
                <salt>7ace5bc9a02a5af61efecd722b7b05e84d106c2a</salt>
                <sign>a112c1c344846202bd87d948cfce1eba7bc535c49dca4752fe8f969abefd05147b4b87fd9332173e242a0f1a78a42eed8c1846d4781a220fd564f0fbce3ff393</sign>
            </auth>
            <action>GetReceipt</action>
            <pid>12345678</pid>
        </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	numeric	Унікальний WGUID платежу, використовується при формуванні посилання
payment.status	string	Статус платежу (1 - зареєстрований, 3 - авторизований, 4 - неуспішний, 5 - успішний)
payment.amount	string	Загальна сума платежу
payment.currency	string	Код валюти
payment.timestamp	date	Дата виконання авторизації/завершення платежу у форматі UNIX-timestamp
payment.transactions	element	Елемент транзакцій
payment.transactions.transaction	element	Елемент транзакції з номером транзакції в системі iPay
payment.transactions.transaction.mch_id	numeric	ID мерчанта
payment.transactions.transaction.smch_id	numeric	Юридична особа, на користь якої здіюйснюється операція
payment.transactions.transaction.invoice	numeric	Сума платежу, у копійках
payment.transactions.transaction.amount	numeric	Сума до сплати (з урахуванням комісії), у копійках
payment.transactions.transaction.desc	string	Опис платежу
payment.transactions.transaction.info	json object	Інформація до платежу, яка надавалась мерчантом при створенні
payment.auth.salt	string	Сіль підпису
payment.auth.sign	string	Підпис запиту
Опціональні поля
payment.payment_type	string	Можливі варіанти: Manual (внесення карткових даних в платіжну форму) / GooglePay / ApplePay. Підключення передачі даного поля здійснюється за кожним окремим мерчантом згідно заявки.

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


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment id="12345678">
	<ident>2b45db39f12555f3ef5dd129eea28d70c5a33ffc</ident>
	<status>1</status>
	<amount>110</amount>
	<currency>UAH</currency>
	<timestamp>1562660681</timestamp>
	<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>

Історія змін

Дата	Версія	Опис змін
2019-07-01	1.0	Налаштування запиту Completion (Завершити платіж з транзікціями)
2019-07-09	1.0.1	Додавання та опис нотифікіції до платежу
2019-07-09	1.0.2	Додавання та опис запиту відмінити авторизацію
2019-09-05	1.0.3	Додавання та опис запиту відмінити платіж
2019-10-03	1.0.4	Додано тестове середовище Sandbox
2019-11-11	1.0.5	Додан запит на повернення коштів
2020-06-12	1.0.6	Додано необов'язкове поле payment.trademark до запиту PaymentCreate
2021-03-22	1.0.7	Додано запит Status (Отримання статусу платежу)
2021-09-27	1.0.8	Додано можливість відправки кількох транзакцій у PaymentCreate
2021-10-26	1.0.9	Додано можливість відправки info у refund та reversal
2023-05-15	1.10	Додано опціональні поля aml
2023-05-29	1.11	Додано новий запит GetReceipt
2023-06-15	1.12	Додано параметр для автоматичного редіректу на сторінки успіху (good) та неуспіху (bad) платежу
2023-08-30	1.13	Розширено список тестових карт, додано карти, які починаються з 5 та 4 для визначення, що це Mastercard/Visa

Checkout API v1.11

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

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

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

Sandbox середовище

Загальна структура запиту

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

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

PaymentCreate (Створити платіж)

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

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

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

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

PaymentCreateWithService (Створити платіж і виконати сервіс)

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

PaymentCreate (з транзакціями) WithService(Створити платіж і виконати сервіс з транзакціями)

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

PaymentCreate з фіскальним чеком

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Reversal (Відмінити авторизацію/платіж)

Відмінити авторизацію:

Відмінити платіж:

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

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

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

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

Refund (Повернення коштів)

Виконати повернення коштів: доступ надається за згодою

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

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

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

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

Status (Статус платежу)

Отримання статусу платежу

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

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

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

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

GetReceipt (Чек платежу)

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

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

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

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

Структура тіла нотифікації

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

Історія змін