iPay masterpass API v1.7.7

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

masterpass – це цифровий гаманець, який зберігає карткові дані в базі даних MasterCard. В цьому гаманці можуть зберігатися картки будь-якої платіжної системи, в т.ч. VISA.

Рішення masterpass, яке описано в даній документації дозволяє значно спростити оплату клієнтом товарів та послуг через Інтернет.

Гаманець masterpass має наступні параметри:

  1. Логін клієнта – це мобільний номер у форматі +380 ХХ ХХХ ХХ ХХ.
  2. Номери карток – в гаманці можна зберігати до 5-и різних карток.

Логіка взаємодії Торговця із гаманцем masterpass наступна. На сайті Торговця повинна бути авторизована зона, особистий кабінет. Логіном або обов’язковим параметром має бути номер телефона клієнта. ВАЖЛИВО! Номер телефона не може бути змінено користувачем без додаткової веріфікації (підтвердження, що саме він являється власником цього телефону. Краще всього, це зробити через одноразовий смс-код).

Коли клієнт знаходиться в Особистому кабінеті Торговця, то під час першого log-in після встановлення masterpass клієнту необхідно запропонувати одну із наступних дій:

  1. Якщо у клієнта є гаманець masterpass, то запропонувати його підключити (залінковати) до особистого кабінету. Процес лінковки означає – що клієнт довіряє даному Торговцю ініціювати запити на авторизацію по його гаманцю.
  2. Якщо у клієнта є гаманець і він вже залінкований, то клієнту необхідно відобразити картки, які у нього зареєстровані в гаманці.
  3. Якщо у клієнта не має гаманця, то запропонувати зареєструвати першу картку для більш зручних розрахунків.
    (всі описані вище шляхи відбуваються на стороні iPay.ua при переадресації клієнта на певний URL)

На сайті Торговця необхідно реалізувати меню для керування картками в гаманці masterpass (додавання, видалення карток). Слід розуміти, що гаманець masterpass, це глобальний гаманець. Коли клієнт додає в нього картку або видаляє, то вона добавляється/видаляється в глобальній базі даних, тобто для всіх Торговців, з якими клієнт залінкововав свій гаманець.

Після того, як клієнт зареєструвався в Особистому кабінеті Торговці та підключив (залінковав) свій гаманець, то користувач може здійснити оплату за допомогою однієї із картки, обрав її із переліку. При цьому Торговець не перенаправляє клієнта на сторінку сервіс-провайдера або еквайера для вводу карткових даних. Все відбувається на стороні Торговця та в ОДИН КЛІК. За допомогою спеціального методу відбувається списання коштів з картки.

При цьому для забезпечення безпеки платежу, компанія iPay.ua может налаштувати перевірку одноразового паролю через смс (OTP_SMS). Тобто для здійснення операції на телефон клієнта, що зареєстровано у masterpass, прийде смс із 6-значним кодом. Цей код клієнт повинен ввести на сайті Торговця для підтвердження. Даний механізм підтвердження клієнта налаштовується на операції вище певної суми.

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

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

- login - ідентифікатор мерчанта
- sign key - ключ для підпису

URL адреса для запитів - https://walletmc.ipay.ua/

Формат передачі - JSON методом POST

Кодування у UTF-8

Алгоритм підпису (поле sign у запиті):
Потрібно об'єднати дві строки в одну: "час у запиті" (поле time у запиті) та "ключ для підпису". Результат зашифрувати алгоритмом SHA-512.

Наприклад:
Поле time у запиті дорівнює "2017-01-01 00:00:00", sign key дорівнює "12347b6ac566d63de29becf2a7e148ef".
Виконуємо об'єднання двох строк в одну: "2017-01-01 00:00:0012347b6ac566d63de29becf2a7e148ef" та шифруємо результат алгоритмом SHA-512, результат шифрування - "b0e540ef2db2505a8a646513785b5e370ad3958430934fe584f89a5e8b17e6d347ad43c763eb34736f4389b73fffc9a3303c3c25aa0081832dfd9a48f2e5a46d" буде значенням поля sign у запиті.

Порядок виконання запитів

Блок схема

diagram

Діаграма послідовності

sequense

Процедура додавання картки до гаманця

Перед додаванням НОВОЇ картки, потрібно виконати запит на перевірку наявновсті номера телефона у програмі masterpass (запит Check).

Можливі 2 варіанти відповіді:
- notexists - немає активного акаунту masterpass;
- invite - номер телефону вже зареєстрований в masterpass, та має прив'язану картку/картки.

У випадку відповіді notexists потрібно:
Виконати запит RegisterByURL та отримати URL форми реєстрації, за яким переадресувати клієнта.
Реєстрація має такі кроки:
- вводяться карткові данні та назва картки;
- відбувається OTP верифікація власника телефону (приходить смс з кодом, який треба ввести на формі реєстрації);
- відбувається LOOKUP верифікація картки (на картці блокується сума 1 грн, значення коду авторизації треба ввести на формі реєстрації).

У випадку відповіді invite потрібно:

Варіант 1: Виконати запит InviteByURL та отримати URL форми реєстрації, за яким переадресувати клієнта.
- відбувається LOOKUP верифікація картки котра вже зареєстрована в masterpass (на картці блокується сума 1 грн, значення коду авторизації треба ввести на формі реєстрації).

Варіант 2: Виконати запит Invite у відповідь надійде token, який потрібно запам’ятати для виконная наступного запиту.
На телефон в смс буде надіслано LOOKUP код зареєстрованої картки в masterpass, який треба передати в запит "Otp".

Для додавання ДОДАТКОВОЇ картки потрібно:
Виконати запит AddcardByURL та отримати URL форми реєстрації, за яким переадресувати клієнта.
Реєстрація додаткової картки має такі кроки:
- вводяться карткові данні та назва картки;
- відбувається LOOKUP верифікація картки (на картці блокується сума 1 грн, значення коду авторизації треба ввести на формі реєстрації).

Процедура створення та підтвердження платежу

Тип платежу (одностадійний або двохстадійний) налаштовується на стороні iPay.

Одностадійний платіж

Для оплати потрібно виконати один запит - PaymentCreate, на картці клієнта списується сума, яка передана в запиті.

Двохстадійний платіж

При виконанні запиту PaymentCreate на картці клієнта блокується сума, яка передана в запиті.

Після запиту PaymentCreate потрібно обов'язково завершити оплату запитом PaymentSale.

При виконанні запиту PaymentSale можливі такі варіанти поведінки системи:
- за наявності заповненого поля "invoice" відбувається остаточне списання суми, яка передана в цьому запиті. Різниця повертається на карту.

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

Структура запитів відрізняється полями action (назва запиту) та body (тіло запиту).

Поле Тип Опис
request object Об'єкт запиту
request.auth object Об'єкт аутентифікації
request.auth.login string ID мерчанта
request.auth.time string Час запиту у часовому поясі Europe/Kiev
request.auth.sign string Підпис запиту
request.action string Назва запиту
request.body object Об'єкт тіла запиту

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Check",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

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

  1. List (Список доступних карток)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "List",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.{card_alias}.card_alias string Назва картки, котру обирає клієнт
    response.{card_alias}.mask string Маска картки (перші 6 і 2 останні цифри номера картки)
    response.{card_alias}.uid string Унікальний ідентифікатор картки
    response.{card_alias}.is_expired integer 0 - картка активна
    1 - срок дії картки закінчився
    response.{card_alias}.is_corporate integer 0 - картка не є корпоративною
    1 - картка є корпоративною

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

    {
    "response": {
        "TEST_CARD": {
            "card_alias": "TEST_CARD",
            "mask": "111122********44",
            "uid": "1B149F911665EBD54331CC3E7DD1BA5496F8F77590455A61511A190231B0FEC6",
            "is_expired": 0,
            "is_corporate": 0

        },
        "TEST_CARD_2": {
            "card_alias": "TEST_CARD_2",
            "mask": "111122********44",
            "uid": "5B149F911665EBD54331CC3E7DD1BA5496F8F77590455A61511A190231B0FEC6",
            "is_expired": 1,
            "is_corporate": 1
        }
    }
}

  2. Check (Перевірити клієнта)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Check",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.user_status string Статус користувача. Може приймати наступні значення:

    - notexists - користувач незареєстрований;
    - exists - користувач зареєстрований і є картки;
    - invite - користувач зареєстрований, але потребує підтвердження на користування картками;
    - blocked - masterpass гаманець заблоковано.

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

    {
    "response": {
        "user_status": "notexists"
    }
}

  3. Invite (Запросити клієнта)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Invite",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.verify string Треба пройти верифікацію MPin
    response.token string Тимчасове унікальне значення токену (потребує збереження для завершення операції), строка довжиною 192

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

    {
    "response": {
        "verify": "mpin",
        "token": "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF ..."
    }
}

  4. UnlinkUser (Відв'язати користувача від Торговця)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "UnlinkUser",
        "body": {
            "msisdn": "380931234567"
        }
    }
}

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

    Поле Тип Опис
    response array Тіло відповіді
    response.status string Статус запиту: success або error

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

    {
    "response": {
        "status": "success"
    }
}

  5. InviteByURL (Запросити клієнта через web інтерфейс)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    lang string Мова інтерфейсу, може приймати одне із значень: ua | ru | en
    Опціональні поля
    success_url string Посилання на сторінку мерчанта після успішного запиту
    error_url string Посилання на сторінку мерчанта після неуспішного запиту

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "InviteByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.url string Посилання на сторінку куди треба перенаправити клієнта для підключення існуючого гаманця

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

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/link"
    }
}

  6. RegisterByURL (Реєстрація гаманця з додаванням першої картки через web інтерфейс)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    lang string Мова інтерфейсу, може приймати одне із значень: ua | ru | en
    Опціональні поля
    success_url string Посилання на сторінку мерчанта після успішного запиту
    error_url string Посилання на сторінку мерчанта після неуспішного запиту

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "RegisterByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.url string Посилання на сторінку куди треба перенаправити клієнта для додавання картки та реєстрації гаманця

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

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/register?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  7. RegisterPurchaseByURL (Реєстрація гаманця з додаванням першої картки та оплата через web інтерфейс)

    8. Якщо користувач успішно сплатив послугу, Торговцю надійде нотифікація методом POST у форматі XML. Документація по нотифікації надається окремо.

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    lang string Мова інтерфейсу, може приймати одне із значень: ua | ru | en
    success_url string Посилання на сторінку мерчанта після успішного запиту
    error_url string Посилання на сторінку мерчанта після неуспішного запиту
    invoice integer Сума платежу, у копійках
    pmt_desc string Призначення платежу, надається мерчантом при створенні (у форматі текст до 100 знаків)
    pmt_info object Інформація до платежу, надається мерчантом при створенні

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "RegisterPurchaseByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error",
            "invoice": 100,
            "pmt_desc": "Сплата за послугу: Інтернет; Номер договору: 1234567; Сума: 100.00 грн.",
            "pmt_info": {
                "custom_field_1": 1234567,
                "custom_field_2": 100
            }
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.url string Посилання на сторінку куди треба перенаправити клієнта для реєстрації гаманця та оплати

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

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/registerpurchase?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  8. AddcardByURL (Додати картку до існуючого гаманця через web інтерфейс)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    lang string Мова інтерфейсу, може приймати одне із значень: ua | ru | en
    Опціональні поля
    success_url string Посилання на сторінку мерчанта після успішного запиту
    error_url string Посилання на сторінку мерчанта після неуспішного запиту

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "AddcardByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.url string Посилання на сторінку куди треба перенаправити клієнта для додавання картки

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

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/addcard?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  9. Otp (Провести верифікацію картки або платежу за допомогою одноразового паролю)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    token string Тимчасове унікальне значення токену (потребує збереження для завершення операції), строка довжиною 192
    value string Перевірочний код

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

     
{
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Otp",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "token": "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF252D0D85C531C0 ...",
            "value": "625348"
        }
    }
}

    Верифікація картки (mpin)

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

    Поле Тип Опис
    response object Тіло відповіді
    response.status string Статус операції, може приймати два значення: "OK" та "FAIL"

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

    {
    "response": {
        "status": "OK"
    }
}

    Верифікація платежу

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

    Показником того, що платіж був успішно підтверджений є статус 5 (одностадійний платіж) або статус 1 (двохстадійний платіж) у відповіді на запит.

    Поле Тип Опис
    response object Тіло відповіді
    response.pmt_id string Номер платежу в системі iPay
    response.invoice string Сума платежу, у копійках
    response.amount string Сума до сплати (з урахуванням комиссії), у копійках
    response.pmt_status string Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний)
    response.card_alias string Назва картки, котру обирає клієнт
    response.card_mask string Маска картки (перші 6 і останні 2 цифри номера картки)
    response.msisdn string Номер телефону, довжина 12 (наприклад 380931234567)
    response.rrn string Поле повертається для статусу платежу - 1, 5
    response.auth_code string Код авторизації. Поле повертається для статусу платежу - 1, 5
    response.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.trm_id string Термінал
    response.bank_response.error_group string Група помилки

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "5",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  10. DeleteCard (Видалити картку)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    card_alias string Назва картки, яку потрібно видалити із гаманця

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "DeleteCard",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "card_alias": "TEST"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.status string Статус операції, може приймати два значення: "OK" та "FAIL"

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

    {
    "response": {
        "status": "OK"
    }
}

  11. CalcPaymentAmount (Розрахувати суму до сплати з урахуванням комісії)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    invoice integer Сума платежу, у копійках

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "CalcPaymentAmount",
        "body": {
            "msisdn": "380931234567",
            "user_id": "750200",
            "invoice": 100
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.invoice integer Сума платежу, у копійках
    response.amount integer Сума до сплати (з урахуванням комісії), у копійках

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

    {
    "response": {
        "invoice": 100,
        "amount": 102
    }
}

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

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    invoice integer Сума платежу, у копійках
    card_alias string Назва картки, котру обирає клієнт
    pmt_desc string Призначення платежу, надається мерчантом при створенні (у форматі текст до 100 знаків).
    Не є обов'язковим, якщо використовується масив транзакцій.
    pmt_info object Інформація до платежу, надається мерчантом при створенні.
    Не є обов'язковим, якщо використовується масив транзакцій.
    threeds_info object
    threeds_info.notification_url string URL, на який буде відправлений результат проходження 3D Secure перевірки
    threeds_info.threeds_requestor_url string Адреса сайту, на якому виконується оплата
    threeds_info.browser_language string Мова браузера користувача, визначений відповідно до IETF BCP 47, наприклад "en-US"
    threeds_info.browser_screen_height string Висота екрану користувача в пікселях
    threeds_info.browser_screen_width string Ширина екрану користувача в пікселях
    threeds_info.browser_accept_header string Точне значення HTTP заголовків, відправлених з браузера користувача на сайт, на якому виконується оплата
    threeds_info.browser_tz string Зміщення часового поясу між Гринвічем та місцевим часом користувача, в хвилинах, наприклад "-120" для часового поясу Europe/Kiev
    threeds_info.browser_user_agent string Точний зміст HTTP заголовка user-agent
    threeds_info.user_ip string IP адреса користувача
    Опціональні поля
    ext_id string ID платежу в системі Торговця, строка до 50 символів (літери (A-Za–z), цифри (0–9), символи (-))
    transactions array Масив транзакцій. Дозволяє розщепити платіж на декілька отримувачів коштів.
    transactions[].invoice integer Сума транзакції, у копійках
    transactions[].smch_id integer ID отримувача коштів, надається iPay
    transactions[].desc integer Призначення платежу, надається мерчантом при створенні (у форматі текст до 100 знаків)
    transactions[].info object Інформація до платежу, надається мерчантом при створенні
    Для Торговців, що інтегруються з фіскалізацією платежів
    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[].name 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 Значення знижки чи надбавки

    Приклад запиту (один отримувач коштів)

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "invoice": 100,
            "card_alias": "TEST",
            "pmt_desc": "Сплата за послугу: Інтернет; Номер договору: 1234567; Сума: 100.00 грн.",
            "pmt_info": {
                "custom_field_1": 1234567,
                "custom_field_2": 100
            },
            "threeds_info":{
                "notification_url": "https://www.merchantsite.com/notification",
                "threeds_requestor_url": "https://www.merchantsite.com",
                "browser_color_depth": "24",
                "browser_language": "en-US",
                "browser_screen_height": "1920",
                "browser_screen_width": "1080",
                "browser_tz": "-120",
                "browser_accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
                "browser_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.66 Safari/537.36",
                "user_ip": "192.168.0.1"
            }
        }
    }
}

    Приклад запиту (декілька отримувачів коштів)

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "invoice": 100,
            "card_alias": "TEST",
            "transactions": [
                {"invoice":50,"smch_id":"5410","desc":"Тестовий платіж","info":{"custom_field_1":"test"}},
                {"invoice":50,"smch_id":"5472","desc":"Тестовий платіж","info":{"custom_field_1":"test"}}
            ],
            "threeds_info":{
                "notification_url": "https://www.merchantsite.com/notification",
                "threeds_requestor_url": "https://www.merchantsite.com",
                "browser_color_depth": "24",
                "browser_language": "en-US",
                "browser_screen_height": "1920",
                "browser_screen_width": "1080",
                "browser_tz": "-120",
                "browser_accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
                "browser_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.66 Safari/537.36",
                "user_ip": "192.168.0.1"
            }
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.pmt_id string Номер платежу в системі iPay
    response.invoice string Сума платежу, у копійках
    response.amount string Сума до сплати (з урахуванням комиссії), у копійках
    response.pmt_status string Статус платежу (0 - потрібна додаткова верифікація, 1 - зареєстрований, 4 - неуспішний, 5 - успішний)
    response.card_alias string Назва картки, котру обирає клієнт
    response.card_mask string Маска картки (перші 6 і останні 2 цифри номера картки)
    response.msisdn string Номер телефону, довжина 12 (наприклад 380931234567)
    response.rrn string Поле повертається для статусу платежу - 1, 5
    response.auth_code string Код авторизації. Поле повертається для статусу платежу - 1, 5
    response.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.trm_id string Термінал
    response.bank_response.error_group string Група помилки
    У випадку потреби верифікації платежу повертаються додаткові поля
    response.security_rate string Тип верифікації платежу, може приймати одне з наступних значень:
    - "2D" (OTP верифікація)
    - "3D" (3D Secure верифікація)
    OTP верифікація
    response.security_data.token string Тимчасове унікальне значення токену (потребує збереження для завершення операції), строка довжиною 192
    3D Secure верифікація
    response.security_data.redirect_url string Посилання куди треба перенаправити клієнта для проходження верифікації
    У випадку успішного платежу повертаються додаткові поля
    response.mch_amount array Дані про зарахування Торговцю
    response.mch_amount[].smch_id string Внутрішній ідентифікатор юридичної особи
    response.mch_amount[].amount string Сума зарахування Торговцю в копійках

    Приклад відповіді (без верифікації)

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": "100",
        "amount": "102",
        "pmt_status": "1",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}
    Приклад відповіді (OTP верифікація) 
    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "0",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        },
        "security_rate": "2D",
        "security_data": {
            "token" : "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF ..."
        }
    }
}
    У випадку OTP верифікації власнику картки на мобільний телефон було відправлено смс повідомлення з кодом. Цей код і token який було повернено у запиті треба передати на запит "Otp", якщо верифікація пройшла успішно кошти на рахунку клієнта будуть списані або заблоковані в залежності від типу платежу - одностадійний або двухстадійний.

    Приклад відповіді (3DS верифікація) 
    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "0",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        },
        "security_rate": "3D",
        "security_data": {
            "redirect_url": "https://example.com/acs"
        }
    }
}

    У випадку 3DS верифікації треба перенаправити користувача по URL, що вказаний у полі security_data.redirect_url. Після проходження верифікації користувачем, результат перевірки буде відправлено POST методом на threeds_info.notification_url вказаний у запиті PaymentCreate, результат перевірки містить наступне поле: threedsData, значення цього поля треба відправити на запит "PaymentVerify3DS", якщо верифікація пройшла успішно кошти на рахунку клієнту будуть списані або заблоковані в залежності від типу платежу - одностадійний або двухстадійний.

  13. PaymentVerify3DS (Провести 3DS верифікацію платежу)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    pmt_id integer Номер платежу в системі iPay
    threeds_data string Результат проходження 3DS верифікації

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentVerify3DS",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_id": "1234567",
            "threeds_data": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol\/fhFKlbV5y9uTs7kk24O5TzscO ..."
        }
    }
}

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

    Показником того, що верифікація платежу пройшла успішно є статус 5 (одностадійний платіж) і статус 1 (двохстадійний платіж) у відповіді на запит.

    Поле Тип Опис
    response object Тіло відповіді
    response.pmt_id string Номер платежу в системі iPay
    response.invoice string Сума платежу, у копійках
    response.amount string Сума до сплати (з урахуванням комісії), у копійках
    response.pmt_status string Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний)
    response.card_alias string Назва картки, котру обирає клієнт
    response.card_mask string Маска картки (перші 6 і останні 2 цифри номера картки)
    response.msisdn string Номер телефону, довжина 12 (наприклад 380931234567)
    response.rrn string Поле повертається для статусу платежу - 1, 5
    response.auth_code string Код авторизації. Поле повертається для статусу платежу - 1, 5
    response.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.trm_id string Термінал
    response.bank_response.error_group string Група помилки
    У випадку успішного платежу повертаються додаткові поля
    response.mch_amount array Дані про зарахування Торговцю
    response.mch_amount[].smch_id string Внутрішній ідентифікатор юридичної особи
    response.mch_amount[].amount string Сума зарахування Торговцю в копійках

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "1",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  14. PaymentSale (Виконати платіж)

    15. Запит виконується лише у тому випадку, якщо це двухстадійний платіж.

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

    Поле Тип Опис
    Обов'язкові поля
    pmt_id integer Номер платежу в системі iPay
    invoice integer Остаточна сума покупки у копійках
    Опціональні поля
    transactions array Масив транзакцій. Дозволяє розщепити платіж на декілька отримувачів коштів.
    transactions[].invoice integer Сума транзакції, у копійках
    transactions[].smch_id integer ID отримувача коштів, надається iPay
    transactions[].desc integer Призначення платежу, надається мерчантом при створенні (у форматі текст до 100 знаків)
    transactions[].info object Інформація до платежу, надається мерчантом при створенні

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentSale",
        "body": {
            "pmt_id": "1234567",
            "invoice": 100
        }
    }
}

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

    Показником того, що платіж був успішно підтверджений є статус 5 у відповіді на запит.

    Поле Тип Опис
    response object Тіло відповіді
    response.pmt_id string Номер платежу в системі iPay
    response.invoice string Сума платежу, у копійках
    response.amount string Сума до сплати (з урахуванням комиссії), у копійках
    response.pmt_status string Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний, 9 - відмінений)
    response.card_alias string Назва картки, котру обирає клієнт
    response.card_mask string Маска картки (перші 6 і останні 2 цифри номера картки)
    response.msisdn string Номер телефону, довжина 12 (наприклад 380931234567)
    response.rrn string Поле повертається для статусу платежу - 1, 5
    response.auth_code string Код авторизації. Поле повертається для статусу платежу - 1, 5
    response.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.trm_id string Термінал
    response.bank_response.error_group string Група помилки
    У випадку успішного платежу повертаються додаткові поля
    response.mch_amount array Дані про зарахування Торговцю
    response.mch_amount[].smch_id string Внутрішній ідентифікатор юридичної особи
    response.mch_amount[].amount string Сума зарахування Торговцю в копійках

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "5",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  15. PaymentCancel (Скасувати платіж)

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

    Поле Тип Опис
    Обов'язкові поля
    pmt_id integer Номер платежу в системі iPay
    Опціональні поля
    amount integer Сума часткового повернення, у копійках

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": "1234567"
        }
    }
}

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

    Показником того, що платіж був успішно відмінений є статус 9 у відповіді на запит.

    Поле Тип Опис
    response object Тіло відповіді
    response.pmt_id string Номер платежу в системі iPay
    response.invoice string Сума платежу, у копійках
    response.amount string Сума до сплати (з урахуванням комісії), у копійках
    response.pmt_status string Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний, 9 - відмінений)
    response.card_alias string Назва картки, котру обирає клієнт
    response.card_mask string Маска картки (перші 6 і останні 2 цифри номера картки)
    response.msisdn string Номер телефону, довжина 12 (наприклад 380931234567)
    response.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.trm_id string Термінал
    response.bank_response.action string Код запиту (опціонально)
    response.bank_response.error_group string Група помилки

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "9",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  16. GetPaymentInvoice (Запросити квитанцію)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    pmt_id integer Номер платежу в системі iPay

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "GetPaymentInvoice",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_id": "1234567"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.invoice string Посилання на квитанцію

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

    {
    "response": {
        "invoice": "https://example.com/invoice/23d53e29722d2b03c954718c1d54b53787985090"
    }
}

  17. GetReceipt (Запросити фіскальний чек)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    pmt_id integer Номер платежу в системі iPay

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "GetReceipt",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_id": 1234567
        }
    }
}

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

    У відповіді повертається чек у форматі PDF з HTTP-заголовком Content-type: application/pdf.

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

    Відповідь повертається у форматі JSON. Фінальним статусом є тільки статус ERROR, в такому випадку створення чеку є неуспішним і робити повторні запити для отриманная чеку не потрібно.

  18. GetPaymentStatus (Статус платежа)

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

    Поле Тип Опис
    Обов'язкові поля
    ext_id string Ідентифікатор платежу мерчанта, що був переданий на запит PaymentCreate

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "GetPaymentStatus",
        "body": {
            "ext_id": "123456"
        }
    }
}

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

    Поле Тип Опис
    response object Тіло відповіді
    response.pmt_id string Номер платежу в системі iPay
    response.invoice string Сума платежу, у копійках
    response.amount string Сума до сплати (з урахуванням комісії), у копійках
    response.pmt_status string Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний, 9 - відмінений)
    response.card_alias string Назва картки, котру обирає клієнт
    response.card_mask string Маска картки (перші 6 і останні 2 цифри номера картки)
    response.msisdn string Номер телефону, довжина 12 (наприклад 380931234567)
    response.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.trm_id string Термінал
    response.bank_response.error_group string Група помилки

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "9",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  19. GetBankList (Отримати список банків)

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

    Тіло запиту (request.body) передається пустим об'єктом.

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "GetBankList",
        "body": {}
    }
}

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

    Поле Тип Опис
    response array Тіло відповіді
    response.[].id integer ID банку
    response.[].name string Назва банку

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

    {
   "response": [
      {
         "id":28,
         "name":"Ощадбанк"
      },
      {
         "id":29,
         "name":"Приватбанк"
      },
      {
         "id":31,
         "name":"Райффайзен банк Аваль"
      },
      {
         "id":41,
         "name":"Ідея Банк"
      },
      {
         "id":49,
         "name":"Конкорд Банк"
      },
      {
         "id":99,
         "name":"Банк Січ"
      }
   ]
}

  20. Ініціювання сесії віджета (InitWidgetSession)

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

    Поле Тип Опис
    Обов'язкові поля
    msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    user_id string Внутрішній ідентифікатор користувача Торговця, дозволено букви, дефіс, цифри, довжина до 45 символів
    pmt_desc string Призначення платежу, надається мерчантом при створенні (у форматі текст до 100 знаків)
    pmt_info object Інформація до платежу, надається мерчантом при створенні
    pmt_info.invoice integer Сума платежу в копійках
    Опціональні поля
    pmt_info.smch_id integer ID отримувача коштів, надається iPay

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "InitWidgetSession",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_desc": "Сплата за послугу: Інтернет; Номер договору: 1234567; Сума: 1.00 грн.",
            "pmt_info": {
                "invoice": 100
            }
        }
    }
}

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

    Поле Тип Опис
    response array Тіло відповіді
    response[].session string Ідентифікатор сеансу

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

    {
    "response": {
        "session": "487fcwbg7xafbT3R652mc8c2794r7l5C"
    }
}

Тестове середовище

У тестовому середовищі верифікація платежів ввімкнена від 5 грн. (500 копійок), якщо сума менше платіж буде проведений без верифікації.

OTP пароль при OTP верифікації платежу є статичним: 471771

Для додавання у гаманець слід використовувати тестові картки.

Код для верифікації номеру телефону або картки є статичним: 111111

Для тестування підключення гаманця у тестовому середовищі, створіть гаманець (додайте першу картку) та виконайте запит UnlinkUser, на запит Check будет повертатись user_status = invite

Номер картки CVC2/CVV2 Срок дії Опис
5506900140100107 [Any] [Any] Успішний платіж, 3DS верифікація
5506900140100206 [Any] [Any] Неуспішний платіж, 3DS верифікація
5204740009900048 [Any] [Any] Успішний платіж, OTP верифікація
5204740009900055 [Any] [Any] Неуспішний платіж, OTP верифікація

Загальні системні помилки

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

Поле Тип Опис
response object Тіло відповіді
response.error string Назва помилки, що виникла

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

{
    "response": {
        "error": "invalid request structure"
    }
}

Перелік можливіх помилок

Помилка Опис
overall error Загальна помилка
invalid request structure Невірна структура запиту
user validation failed Помилка валідації поля "user_id". Даний номер телефону вже прив'язаний до іншого користувача в особистому кабінеті Торговця.
unknown field {field_name} У запиті передано поле, яке невідоме системі
invalid expm Невірне значення expm
invalid expy Невірне значення expy
invalid cvv Невірне значення cvv
invalid value Невірне значення value
invalid pan Невірне значення pan
invalid auth Помилка аутентифікації
invalid auth time Невірний час запиту
access denied Доступ заборонено
invalid msisdn Невірне значення msisdn
card is expired Термін дії картки закінчився
no card Картка не знайдена
try again later Будь-ласка, спробуйте повторити запит пізніше

Групи помилок

Якщо при виконанні запиту PaymentCreate, Otp, PaymentVerify3DS, PaymentSale був отриманий статус 4, в об'єкті bank_response поле error_group містить групу помилки банку.

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

{
    "response": {
        "pmt_id": "1234567",
        "invoice": "100",
        "amount": "102",
        "pmt_status": "4",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "42",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

Перелік груп помилок

Група помилки Опис
41 Відмова банку. Будь-ласка, перевірте, що на картці достатньо коштів і не перевищено ліміт на проведення операцій через Інтернет.
42 Відмова банку, недостатньо коштів для проведення операції.
43 Відмова банку, перевищено ліміт суми операції. Будь ласка, зв'яжіться з Вашим банком, щоб збільшити ліміт на проведення операцій через Інтернет.
50 Невірний CVV код. Спробуйте ще раз.
51 Помилка 3D Secure верифікації. Спробуйте ще раз.
52 Помилка з'єднання, повторіть спробу пізніше.
54 Відмова служби безпеки
55 Під час обробки платежу сталася помилка.

Перелік банків

ID банку Назва
28 Ощадбанк
29 Приватбанк
31 Райффайзен банк Аваль
41 Ідея Банк
49 Конкорд банк
99 Банк Січ

Підключення віджета masterpass

1. Потрібно виконати запит InitWidgetSession, у відповіді надійде ідентифікатор сеансу, який є актуальним впродовж 30 хвилин.
2. Розмістити на сторінці код виклику віджета. Приклад сторінки з підключенним віджетом:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta content="width=device-width, initial-scale=1.0" name="viewport">
    <title>iPay masterpass widget</title>
    <script type="text/javascript" src="https://widgetmp.ipay.ua/widget.js"></script>
</head>
<body>
<a href="#" onclick="MasterpassWidget.open(
            {
                partner: 'test',
                lang: 'ru', 
                session: '123fcwbg7xafbT3R652mc4c2794r7l5C'
            },
            // функція, яка буде виконана після закриття віджету
            function() {},
            // функція, яка буде виконана після успішної оплати
            function() {},
            // функція, яка буде виконана після помилкової оплати
            function() {}
);">
    <img src="https://widgetmp.ipay.ua/mp-button.svg">
</a>
</body>
</html>
До методу MasterpassWidget.open потрібно передати об'єкт з наступними полями:
- partner - ідентифікатор Торговця (login);
- lang - мова інтерфейсу ( ru | ua);
- session - ідентифікатор сеансу отриманий на запит InitWidgetSession.

Якщо користувач успішно сплатив послугу, Торговцю надійде нотифікація методом POST у форматі XML. Документація по нотифікації надається окремо.

Історія змін

Дата Версія Опис змін
2016-09-14 1.1 Налаштування запитів PaymentCreate, PaymentSale.
2016-12-02 1.2 Налаштування запитів RegisterByURL, DeleteCard.
2016-12-12 1.3 Налаштування запиту InviteByURL.
2017-02-13 1.4 Додано блок схему та діаграму послідовності.

Методи PaymentStatus, PaymentCancel виключено з прод. середовища у зв`язку з модифікацією.
2017-02-17 1.4.1 Додано поле сума в запиті PaymentSale та можливість часткового повернення суми після списання.
2017-02-21 1.4.2 Виправлення помилок документації в розділі "Процедура створення та підтвердження платежу" та запиті PaymentSale.
2017-02-22 1.5 Додано запит PaymentCancel - відміна платежу.
2017-02-24 1.6 Додано запит StatusRequest - перевірка запиту.

Змінено запит PaymentCancel: додано обовязковий параметр "msisdn", для отримання корректної відповіді StatusRequest по цьому методу.
2017-03-06 1.6.1 Додано опціональний параметр "guid", за яким можна перевіряти статус запиту.
2017-03-10 1.6.2 Повернено у документацію метод Invite.
2017-03-15 1.6.5 Додано метод AddcardByURL - додавання картки до існуючого гаманця.
2017-03-22 1.6.7 Оновлено розділ "Загальна інформація".
2017-04-11 1.6.8 Оновлено запити PaymentCreate, PaymentSale, PaymentCancel: до відповіді додано поле bank_response.

Додано розділ "Коди помилок банку".
2017-05-16 1.6.9 Оновлено запит PaymentCreate: додано верифікацію платежу OTP, 3DS.

Додано новий банк-еквайер Приватбанк.
2017-06-02 1.7.0 В методи AddcardByURL, InviteByURL та RegisterByURL додано додаткові параметри success_url, error_url
(посилання на сторінку Торговця після успішного чи неуспішного запиту)
2017-06-15 1.7.1 Додано наступні запити:
- CalcPaymentAmount (розрахувати суму до сплати (з урахуванням комісії))
- TestInvite (тестування запрошення клієнта)
2017-06-22 1.7.2 До кожного запиту додано поле user_id (внутрішній ідентифікатор користувача Торговця)
2017-07-03 1.7.3 Додано запит RegisterPurchaseByURL (Реєстрація гаманця з додаванням першої картки та оплата через web інтерфейс)
2017-07-13 1.7.4 Додано одностадійний платіж.
2017-07-24 1.7.5 Додано поле is_expired (срок дії картки закінчився чи ні) у відповіді на запит List.
2017-09-11 1.7.6 Додано новий банк-еквайер Райффайзен Банк Аваль.

Додано поле is_corporate (картка корпоративна чи ні) у відповіді на запит List.
2022-06-02 1.7.7 Додано новий запит GetBankList.