Ipay MasterPass API v1.7.6

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

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

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

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

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

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

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

  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".
Інші поля для відправлення запиту Mpin виконуються додатком.

Для додавання ДОДАТКОВОЇ картки потрібно: Виконати запит RegisterByURL та отримати 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
            }
        }
    }
                
  3. Check (Перевірити клієнта)

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

    Поле Тип Опис
    Обов'язкові поля
    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"
        }
    }
                
  5. Invite (Запросити клієнта)

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

    Поле Тип Опис
    Обов'язкові поля
    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 ..."
        }
    }
  7. UnlinkUser (Відв'язати користувача від Торговця)

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

    Поле Тип Опис
    Обов'язкові поля
    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"
        }
    }
  9. InviteByURL (Запросити клієнта через web інтерфейс)

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

    Поле Тип Опис
    Обов'язкові поля
    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"
        }
    }
  11. RegisterByURL (Реєстрація гаманця з додаванням першої картки через web інтерфейс)

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

    Поле Тип Опис
    Обов'язкові поля
    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"
        }
    }
    
  13. RegisterPurchaseByURL (Реєстрація гаманця з додаванням першої картки та оплата через web інтерфейс)

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

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

    {
        "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
                },
                "guid": "AD68E7675FE111E79A65005056B960DF"
            }
        }
    }
    

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

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

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

    {
        "response": {
            "url": "https://walletmp.ipay.ua/ru/partner/example/registerpurchase?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
        }
    }
    
  15. AddcardByURL (Додати картку до існуючого гаманця через web інтерфейс)

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

    Поле Тип Опис
    Обов'язкові поля
    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"
        }
    }
    
  17. Otp (Провести верифікацію картки або платежу за допомогою одноразового паролю)

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

    Поле Тип Опис
    Обов'язкові поля
    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.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.rc string Код відповіді
    response.bank_response.action 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": ""
            }
        }
    }
  19. CalcPaymentAmount (Розрахувати суму до сплати з урахуванням комісії)

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

    Поле Тип Опис
    Обов'язкові поля
    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
        }
    }
  21. PaymentCreate (Створити платіж)

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

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

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

    {
        "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
                },
                "guid": "AD68E7675FE111E79A65005056B960DF"
            }
        }
    }
    

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

    {
        "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"}}
                ],
                "guid": "AD68E7675FE111E79A65005056B960DF"
            }
        }
    }
    

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

    Поле Тип Опис
    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.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.rc string Код відповіді
    response.bank_response.action string Код запиту (опціонально)
    response.bank_response.error_group string Група помилки
    У випадку потреби верифікації платежу повертаються додаткові поля
    response.secure string Тип верифікації платежу, може приймати одне з наступних значень:
    - "otp" (OTP верифікація)
    - "3ds" (3DS верифікація)
    OTP верифікація
    response.token string Тимчасове унікальне значення токену (потребує збереження для завершення операції), строка довжиною 192
    3DS верифікація
    response.ascUrl string Посилання куди треба перенаправити клієнта для проходження 3DS верифікації
    response.pareq string 3D Secure результати аутентифікації
    response.md string Унікальний ID транзакції
    У випадку успішного платежу повертаються додаткові поля
    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": ""
            }
        }
    }
    
    Приклад відповіді (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": ""
            },
            "secure": "otp",
            "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": ""
            },
            "secure": "3ds",
            "ascUrl": "https://example.com/acs",
            "pareq": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol\/fhFKlbV5y9uTs7kk24O5TzscO ...",
            "md": "CmD2M2QzYmItOBJjZS00YWAjLTlhMTctNjRiOWYzNWQyNTFk"
        }
    }
    

    У випадку 3DS верифікації у відповіді додатково повертаються наступні поля: ascUrl, pareq, md.
    Поле ascUrl - це посилання куди треба перенаправити клієнта для проходження 3DS верификації.
    Поля pares та md слід передавати методом POST на ascUrl.

    Приклад форми для відправки клієнта на проходження 3DS верификації:
                
    <form name="MPIform" action='{url}' method="POST">
        <input type="hidden" name="PaReq" value='{pareq}'>
        <input type="hidden" name="MD" value='{md}'>
        <input type="hidden" name="TermUrl" value='{TermUrl}'>
    </form>            
    Поле TermUrl - це посилання на сторінку Торговця куди банк перенаправить клієнта після проходження верифікації і поверне результати POST методом, які містять наступні поля: PaRes, MD. Ці результати треба відправити на запит "PaymentVerify3DS", якщо верифікація пройшла успішно кошти на рахунку клієнту будуть списані або заблоковані в залежності від типу платежу - одностадійний або двухстадійний.
  23. PaymentVerify3DS (Провести 3DS верифікацію платежу)

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

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

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

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

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

    Показником того, що верифікація платежу пройшла успішно є статус 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.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.rc string Код відповіді
    response.bank_response.action 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": ""
            }
        }
    }
  25. PaymentSale (Виконати платіж)

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

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

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

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

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

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

    Показником того, що платіж був успішно підтверджений є статус 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.bank_response object Відповідь банку
    response.bank_response.bank_id string ID банку
    response.bank_response.rc string Код відповіді
    response.bank_response.action 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": ""
            }
        }
    }
  27. PaymentCancel (Скасувати платіж)

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

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

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

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

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

    Показником того, що платіж був успішно відмінений є статус 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.rc 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": ""
            }
        }
    }
  29. GetPaymentInvoice (Запросити квитанцію)

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

    Поле Тип Опис
    Обов'язкові поля
    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"
        }
    }
    
  31. DeleteCard (Видалити картку)

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

    Поле Тип Опис
    Обов'язкові поля
    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"
        }
    }
  33. StatusRequest (Статус запиту)

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

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

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

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

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

    Поле Тип Опис
    response array Тіло відповіді
    response[].type string Тип запиту
    response[].msisdn string Номер телефону, довжина 12 цифр (наприклад 380931234567)
    response[].response string Відповідь у форматі json
    response[].date string Дата на момент запиту

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

    {
        "response": [
            {
                "type": "PaymentCreate",
                "msisdn": "380931234567",
                "response": "{"pmt_id":"1234567","invoice":"200000","amount":"200000","pmt_status":"1",
                            "card_alias":"TEST","card_mask":"111122********44","msisdn":"380931234567",
                            "bank_response":"{"bank_id":28,"rc":"00","action":"0","error_group":""}"}",
                "date": "2017-01-01 15:47:27"
            }
        ]
    }
    
  35. Ініціювання сесії віджета (InitWidgetSession)

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

    Поле Тип Опис
    Обов'язкові поля
    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
invalid clientIp Невірне значення clientIp
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"
        }
    }
}

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

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

Підключення віджета 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.