iPay masterpass API v1.7.7 Doc

iPay masterpass API v1.7.7 УКР РУ [doc.php?lang=ru] EN Загальна інформація Доступи й налаштування Порядок виконання запитів Процедура додавання картки до гаманця Процедура створення та підтвердження платежу Загальна структура запиту Перелік запитів Список доступних карток Перевірити клієнта Запросити клієнта Відв'язати користувача від Торговця Запросити клієнта через web інтерфейс Додати картку при регістрації гаманця через web інтерфейс Реєстрація гаманця з додаванням першої картки та оплата через web інтерфейс Додати картку до існуючого гаманця через web інтерфейс Провести верифікацію картки або платежу за допомогою одноразового паролю Видалити картку Розрахувати суму до сплати (з урахуванням комісії) Створити платіж Провести 3DS верифікацію платежу Виконати платіж Скасувати платіж Запросити квитанцію Запросити фіскальний чек Статус платежа Отримати список банків Ініціювання сесії віджета Тестове середовище Загальні системні помилки Групи помилок Перелік банків Підключення віджета masterpass Історія змін Загальна інформація masterpass – це цифровий гаманець, який зберігає карткові дані в базі даних MasterCard. В цьому гаманці можуть зберігатися картки будь-якої платіжної системи, в т.ч. VISA. Рішення masterpass, яке описано в даній документації дозволяє значно спростити оплату клієнтом товарів та послуг через Інтернет. Гаманець masterpass має наступні параметри: Логін клієнта – це мобільний номер у форматі +380 ХХ ХХХ ХХ ХХ. Номери карток – в гаманці можна зберігати до 5-и різних карток. Логіка взаємодії Торговця із гаманцем masterpass наступна. На сайті Торговця повинна бути авторизована зона, особистий кабінет. Логіном або обов’язковим параметром має бути номер телефона клієнта. ВАЖЛИВО! Номер телефона не може бути змінено користувачем без додаткової веріфікації (підтвердження, що саме він являється власником цього телефону. Краще всього, це зробити через одноразовий смс-код). Коли клієнт знаходиться в Особистому кабінеті Торговця, то під час першого log-in після встановлення masterpass клієнту необхідно запропонувати одну із наступних дій: Якщо у клієнта є гаманець masterpass, то запропонувати його підключити (залінковати) до особистого кабінету. Процес лінковки означає – що клієнт довіряє даному Торговцю ініціювати запити на авторизацію по його гаманцю. Якщо у клієнта є гаманець і він вже залінкований, то клієнту необхідно відобразити картки, які у нього зареєстровані в гаманці. Якщо у клієнта не має гаманця, то запропонувати зареєструвати першу картку для більш зручних розрахунків. (всі описані вище шляхи відбуваються на стороні 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 у запиті. Порядок виконання запитів Блок схема Діаграма послідовності Процедура додавання картки до гаманця Перед додаванням НОВОЇ картки, потрібно виконати запит на перевірку наявновсті номера телефона у програмі 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" } } } Перелік запитів List (Список доступних карток) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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 } } } Check (Перевірити клієнта) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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" } } Invite (Запросити клієнта) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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 ..." } } UnlinkUser (Відв'язати користувача від Торговця) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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" } } InviteByURL (Запросити клієнта через web інтерфейс) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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" } } RegisterByURL (Реєстрація гаманця з додаванням першої картки через web інтерфейс) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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" } } RegisterPurchaseByURL (Реєстрація гаманця з додаванням першої картки та оплата через web інтерфейс) Якщо користувач успішно сплатив послугу, Торговцю надійде нотифікація методом 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" } } AddcardByURL (Додати картку до існуючого гаманця через web інтерфейс) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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" } } Otp (Провести верифікацію картки або платежу за допомогою одноразового паролю) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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 } } } DeleteCard (Видалити картку) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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" } } CalcPaymentAmount (Розрахувати суму до сплати з урахуванням комісії) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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 } } PaymentCreate (Створити платіж) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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", якщо верифікація пройшла успішно кошти на рахунку клієнту будуть списані або заблоковані в залежності від типу платежу - одностадійний або двухстадійний. PaymentVerify3DS (Провести 3DS верифікацію платежу) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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 } } } PaymentSale (Виконати платіж) Запит виконується лише у тому випадку, якщо це двухстадійний платіж. Структура тіла запиту Поле Тип Опис Обов'язкові поля 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 } } } PaymentCancel (Скасувати платіж) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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 } } } GetPaymentInvoice (Запросити квитанцію) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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" } } GetReceipt (Запросити фіскальний чек) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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, в такому випадку створення чеку є неуспішним і робити повторні запити для отриманная чеку не потрібно. GetPaymentStatus (Статус платежа) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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 } } } GetBankList (Отримати список банків) Структура тіла запиту Тіло запиту (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":"Банк Січ" } ] } Ініціювання сесії віджета (InitWidgetSession) Структура тіла запиту Поле Тип Опис Обов'язкові поля 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. Розмістити на сторінці код виклику віджета. Приклад сторінки з підключенним віджетом: До методу 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.