Checkout API v1.11

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

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

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

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

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

     

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

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

  2. Після створення платежу у відповідь повертається 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>
    
  3. Completion (Завершити платіж)

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

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

    Поле Тип Опис
    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>
            
  5. Completion (Завершити платіж з транзікціями)

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

    Принцип роботи 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>
            
  7. Reversal (Відмінити авторизацію/платіж)

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

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

    Запит може бути виконано лише за умови успішної предавторизації платежу,
    та платіж знаходиться у статусі 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>
            
  9. Refund (Повернення коштів)

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

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

    Запит може бути виконано лише за умови успішної оплати платежу,
    та платіж знаходиться у статусі 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>
            
  11. Status (Статус платежу)

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

    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>
            
  13. GetReceipt (Чек платежу)

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

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

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

    Поле Тип Опис
    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>
            
  15. Нотіфікація платежів

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