Документація iPay Google Pay API

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

Google Pay™ - це миттєвий платіжний спосіб від Google, який дозволяє просто і швидко оплатити карткою, без необхідності вводити платіжні дані для кожного платежу. Дані картки надійно зберігаються в Google. Даний метод доступний для оплати у мобільних додатках на будь-яких пристроях Android і при здійсненні платежу у браузері Chrome.

2. Інтеграція

2.1 Підключення через сторінку iPay

При такому способі підключення немає необхідності в додаткових інтеграціях. Кнопка Google Pay буде відображена на сторінці iPay.

2.2 Пряма інтеграція через Google Pay API

Щоб підключити Google Pay до веб-сайту, дійте відповідно до інструкцій, розміщених за посиланнями:

Документація: https://developers.google.com/pay/api/web

Вимоги з брендування: https://developers.google.com/pay/api/web/guides/brand-guidelines

Щоб підключити Google Pay до мобільного додатку, дійте відповідно до інструкцій, розміщених за посиланнями:

Документація: https://developers.google.com/pay/api/android

Вимоги з брендування: https://developers.google.com/pay/api/android/guides/brand-guidelines

Значення параметрів, які передаються в PaymentMethod об'єкті:

allowedAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];
allowedCardNetworks = ['MASTERCARD', 'VISA'];
tokenizationSpecification.type = "PAYMENT_GATEWAY";
tokenizationSpecification.parameters.gateway = "ipayua";
tokenizationSpecification.parameters.gatewayMerchantId = "YOUR_IPAY_MERCHANT_ID".

3. Проведення платежу

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

Для взаємодії з iPay Google Pay API слід отримати ідентифікатор мерчанта (login) та ключ для підпису (sign key).

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

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

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

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

Створення та підтвердження платежу

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

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

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

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

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

Після запиту PaymentCreate потрібно обов'язково завершити оплату запитом PaymentSale. Якщо в запиті PaymentSale значення поля invoice менше, ніж було в запиті PaymentCreate, різниця повертається на картку користувачеві. При успішному завершенні запиту у відповіді повертається статус платежу = 5.

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

Google Pay доступний у тестовому середовищі, встановіть значення "TEST" для свойства "environment" об'єкта PaymentOptions.

Тестові платежі виконуються без списання з картки.

3D Secure ввімкнений для платежу на суму більше 500 грн.

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

Поле Тип Опис
request object Об'єкт запиту
request.version string Версія API
request.auth object Об'єкт аутентифікації
request.auth.login string ID мерчанта
request.auth.time string Час запиту у часовому поясі Europe/Kiev
Формат: YYYY-MM-DD HH:MM:SS
Приклад: 2017-01-01 00:00:00
request.auth.sign string Підпис запиту
request.action string Назва запиту
request.body object Об'єкт тіла запиту

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "pmt_desc": "Test payment ",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "ext_id": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}

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

3.4.1 CalculateFee

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

Поле Тип Опис
Обов'язкові поля
invoice integer Сума платежу, у копійках

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "CalculateFee",
        "body": {
            "invoice": 100
        }
    }
}

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

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

Пример ответа

{
    "response": {
        "invoice":"1000",
        "amount":"1100",
        "fee":"100",
    }
}

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

Поле Тип Опис
Обов'язкові поля
invoice integer Сума платежу, у копійках
token string Токен GooglePay у форматі JSON закодований в Base64 (поле не є обов'язковим якщо передано поле recurrent_token)
pmt_desc string Опис платежу
pmt_info object Інформація до платежу, надається мерчантом при створенні
threeds_info object Дані для 3D Secure верифікації
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_color_depth 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
Опціональні поля
ext_id string Унікальний ідентифікатор оплати в системні мерчанта (максимальна довжина - 50 символів)
msisdn string Номер телефону
deferred_payment bool Платіж буде виконано без списання коштів, далі платіж потрібно завершити через запит ProcessPayment
recurrent bool Рекурентний платіж (true або false). Використовується для першого запиту щоб отримати у відповідь recurrent_token (якщо рекурент можливий по даному платежу)
recurrent_token string Токен рекурентного платежу
transactions array Масив транзакцій. Дозволяє розщепити платіж на декілька отримувачів коштів.
transactions[].invoice integer Сума транзакції, у копійках
transactions[].smch_id integer ID отримувача коштів, надається iPay
transactions[].desc integer Призначення платежу, надається мерчантом при створенні (у форматі текст до 100 знаків)
transactions[].info object Інформація до платежу, надається мерчантом при створенні
Реквізити відправника та одержувача
sender object Дані відправника
sender.lastname string Прізвище відправника
sender.firstname string Ім'я відправника
sender.middlename string По-батькові відправника
sender.document string Номер паспорта відправника (наприклад: АН123456)
sender.address string Адреса відправника (наприклад: Київ, вул. Тестова, 10)
sender.identification_number string ІПН (Індивідуальний податковий номер) / ЄДРПОУ (ідентифікаційний код суб'єкта Єдиного державного реєстру підприємств України)
sender.account_number string Розрахунковий рахунок відправника (фіз.особа/підприємство)
receiver object Дані одержувача
receiver.lastname string Прізвище одержувача
receiver.firstname string Ім'я одержувача
receiver.middlename string По-батькові одержувача
receiver.document string Номер документа одержувача (например: АН123456)
receiver.address string Адреса одержувача (наприклад: Київ, вул. Тестова, 10)
receiver.identification_number string ІПН (Індивідуальний податковий номер) / ЄДРПОУ (ідентифікаційний код суб'єкта Єдиного державного реєстру підприємств України)
receiver.account_number string Розрахунковий рахунок одержувача (фіз.особа/підприємство)
Для Торговців, що інтегруються з фіскалізацією платежів
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 Значення знижки чи надбавки
receipt_data.delivery_email string Email для відправки чека

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "pmt_desc": "Test payment",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "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"
            },
            "ext_id": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "transactions": [
                {"invoice":50,"smch_id":"5410","desc":"Тестовий платіж","info":{"custom_field_1":"test"}},
                {"invoice":50,"smch_id":"5472","desc":"Тестовий платіж","info":{"custom_field_1":"test"}}
            ]
        }
    }
}

Приклад запиту (дані для фіскалізації платежу)

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "pmt_desc": "Test payment",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "receipt_data": {
                "cashier_id": 1,
                "cash_register_id": 1,
                "goods":[
                    {
                        "id": "e0e58e8e-af5d-430f-8204-459ab547a4b8",
                        "code": "Код товару 1",
                        "name": "Назва товару 1",
                        "barcode": "A12345",
                        "price": 100,
                        "quantity": 1000
                    },
                    {
                        "id": "35420435-fabf-4936-bf72-a6af8755e43a",
                        "code": "Код товару 2",
                        "name": "Назва товару 2",
                        "barcode": "A12345",
                        "price": 400,
                        "quantity": 1000
                    }
                ],
                "discounts": [
                    {
                        "type":"DISCOUNT",
                        "mode":"PERCENT",
                        "value":10
                    }
                ]
            }
        }
    }
}

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

Поле Тип Опис
response object Об'єкт відповіді
response.pmt_id integer ID платежу в системі iPay
response.ext_id string Унікальний ідентифікатор оплати в системні мерчанта
response.invoice integer Сума платежу, у копійках
response.amount integer Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status integer Статус платежу (1 – потрібна верифікація платежу, 3 – передавторизація коштів успішна (тільки для двостадійного платежу), 4 - неуспішний, 5 - успішний, 14 - відмова служби безпеки, 17 - платіж виконано без списання)
response.card_mask string Маска картки
response.bank_response object Відповідь банку
response.bank_response.error_group integer Група помилки
response.bank_acquirer_name string Назва банка екваєра
response.rrn string RRN (повертається для статусу платежу - 3, 5)
response.terminal_id string|null ID терміналу (повертається для статусу платежу - 3, 5)
response.auth_code string Код авторізації (повертається для статусу платежу - 3, 5)
response.auth_code string Код авторізації (повертається для статусу платежу - 3, 5)
response.transactions array Масив транзакцій
response.transactions[].trn_id integer ID транзакції
response.transactions[].smch_id integer ID юр.особи
response.transactions[].invoice integer Сума транзакції у копійках
response.transactions[].amount integer Сума транзакції (з урахуванням комісії) у копійках
У випадку успішного платежу повертаються додаткові поля
response.recurrent_token string Токен рекурентного платежу, повертається якщо на запит PaymentCreate був переданий recurrent = true і платіж підтримує рекурент
response.mch_amount array Дані про зарахування Торговцю
response.mch_amount[].smch_id string Внутрішній ідентифікатор юридичної особи
response.mch_amount[].amount string Сума зарахування Торговцю в копійках

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

Приклад відповіді (3D Secure)

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 1,
        "security_rate": "3D",
        "security_data": {
            "redirect_url": "https://example.com/acs"
        },
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

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

3.4.3 PaymentVerify3DS

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

Поле Тип Опис
Обов'язкові поля
pmt_id integer ID платежу в системі iPay
threeds_data string Результат проходження 3DS верифікації
Опціональні поля

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentVerify3DS",
        "body": {
            "pmt_id": 1234567,
            "threeds_data": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol..."
        }
    }
}

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

Поле Тип Опис
response object Об'єкт відповіді
response.pmt_id integer ID платежу в системі iPay
response.invoice integer Сума платежу, у копійках
response.amount integer Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status integer Статус платежу (3 – передавторизація коштів успішна (тільки для двостадійного платежу), 4 - неуспішний, 5 - успішний)
response.card_mask string Маска картки
response.bank_response object Відповідь банку
response.bank_response.error_group integer Група помилки
response.bank_acquirer_name string Назва банка екваєра
response.rrn string RRN (повертається для статусу платежу - 3, 5)
response.terminal_id string|null ID терміналу (повертається для статусу платежу - 3, 5)
response.terminal_id string|null ID терміналу (повертається для статусу платежу - 3, 5)
response.auth_code string Код авторізації (повертається для статусу платежу - 3, 5)
response.transactions array Масив транзакцій
response.transactions[].trn_id integer ID транзакції
response.transactions[].smch_id integer ID юр.особи
response.transactions[].invoice integer Сума транзакції у копійках
response.transactions[].amount integer Сума транзакції (з урахуванням комісії) у копійках
У випадку успішного платежу повертаються додаткові поля
response.recurrent_token string Токен рекурентного платежу, повертається якщо на запит PaymentCreate був переданий recurrent = true і платіж підтримує рекурент
response.mch_amount array Дані про зарахування Торговцю
response.mch_amount[].smch_id string Внутрішній ідентифікатор юридичної особи
response.mch_amount[].amount string Сума зарахування Торговцю в копійках

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

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

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

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentSale",
        "body": {
            "pmt_id": 1234567,
            "invoice": 100
        }
    }
}

Приклад запиту з транзакціями

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentSale",
        "body": {
            "pmt_id": "1234567",
            "transactions":[
                {
                    "invoice":20,
                    "smch_id":111,
                    "desc":"Test1",
                    "info":{
                        "custom_merchant_field":12345
                    }
                },
                {
                    "invoice":25,
                    "smch_id":222,
                    "desc":"Test2",
                    "info":{
                        "custom_merchant_field":67890
                    }
                }
            ]
        }
    }
}

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

Поле Тип Опис
response object Об'єкт відповіді
response.pmt_id integer ID платежу в системі iPay
response.invoice integer Сума платежу, у копійках
response.amount integer Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status integer Статус платежу (4 - неуспішний, 5 - успішний)
response.card_mask string Маска картки
response.bank_response object Відповідь банку
response.bank_response.error_group integer Група помилки
response.bank_acquirer_name string Назва банка екваєра
response.rrn string RRN (повертається для статусу платежу - 3, 5)
response.terminal_id string|null ID терміналу (повертається для статусу платежу - 3, 5)
response.auth_code string Код авторізації (повертається для статусу платежу - 3, 5)
response.transactions array Масив транзакцій
response.transactions[].trn_id integer ID транзакції
response.transactions[].smch_id integer ID юр.особи
response.transactions[].invoice integer Сума транзакції у копійках
response.transactions[].amount integer Сума транзакції (з урахуванням комісії) у копійках
У випадку успішного платежу повертаються додаткові поля
response.recurrent_token string Токен рекурентного платежу, повертається якщо на запит PaymentCreate був переданий recurrent = true і платіж підтримує рекурент
response.mch_amount array Дані про зарахування Торговцю
response.mch_amount[].smch_id string Внутрішній ідентифікатор юридичної особи
response.mch_amount[].amount string Сума зарахування Торговцю в копійках

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

Структура тіла запиту (для платежів з однією транзакцією)

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

Приклад запиту (для платежів з однією транзакцією)

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": 1234567
        }
    }
}

Структура тіла запиту (для платежів з декількома транзакціями)

Поле Тип Опис
Обов'язкові поля
pmt_id integer ID платежу в системі iPay
Опціональні поля
transactions array Масив транзакцій
transactions[].trn_id integer ID транзакції
transactions[].amount integer Сума часткового повернення, у копійках

Приклад запиту (для платежів з декількома транзакціями)

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": 1234567,
            "transactions": [
                {
                  "trn_id": 6636,
                  "amount": 50
                },
                {
                  "trn_id": 6638,
                  "amount": 30
                }
            ]
        }
    }
}

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

Поле Тип Опис
response object Об'єкт відповіді
response.pmt_id integer ID платежу в системі iPay
response.invoice integer Сума платежу, у копійках
response.amount integer Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status integer Статус платежу (4 - неуспішний, 9 - успішна відміна)
response.card_mask string Маска картки
response.bank_response object Відповідь банку
response.bank_response.error_group integer Група помилки
response.bank_acquirer_name string Назва банка екваєра
response.transactions array Масив транзакцій
response.transactions[].trn_id integer ID транзакції
response.transactions[].smch_id integer ID юр.особи
response.transactions[].invoice integer Сума транзакції у копійках
response.transactions[].amount integer Сума транзакції (з урахуванням комісії) у копійках

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 9,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

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

Поле Тип Опис
Обов'язковим є одне поле - pmt_id або ext_id
pmt_id integer ID платежу в системі iPay
ext_id integer ID платежу в системі Торговця

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2019-02-19 10:47:35",
            "sign": "a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action": "GetPaymentStatus",
        "body": {
            "pmt_id": 1234567
        }
    }
}

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

Поле Тип Опис
response object Об'єкт відповіді
response.pmt_id string ID платежу в системі iPay
response.invoice string Сума платежу, у копійках
response.amount string Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status string Статус платежу (4 - неуспішний, 5 - успішний)
response.card_mask string Маска картки
response.bank_response object Відповідь банку
response.bank_response.error_group integer Група помилки
response.bank_acquirer_name string Назва банка екваєра
response.rrn string RRN (повертається для статусу платежу - 3, 5)
response.auth_code string Код авторізації (повертається для статусу платежу - 3, 5)
response.transactions array Масив транзакцій
response.transactions[].trn_id integer ID транзакції
response.transactions[].smch_id integer ID юр.особи
response.transactions[].invoice integer Сума транзакції у копійках
response.transactions[].amount integer Сума транзакції (з урахуванням комісії) у копійках
У випадку успішного платежу повертаються додаткові поля
response.recurrent_token string Токен рекурентного платежу, повертається якщо на запит PaymentCreate був переданий recurrent = true і платіж підтримує рекурент
response.mch_amount array Дані про зарахування Торговцю
response.mch_amount[].smch_id string Внутрішній ідентифікатор юридичної особи
response.mch_amount[].amount string Сума зарахування Торговцю в копійках

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

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

Поле Тип Опис
Обов'язкові поля
pmt_id integer ID платежу в системі iPay

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2019-02-19 10:47:35",
            "sign": "a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action": "GetPaymentInvoice",
        "body": {
            "pmt_id": 1234567
        }
    }
}

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

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

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

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

Отриманная фіскального чеку для Торговців, що виконують інтеграцію з фіскалізацією платежів.

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

Поле Тип Опис
Обов'язкові поля
pmt_id integer ID платежу в системі iPay

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2019-02-19 10:47:35",
            "sign": "a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action": "GetReceipt",
        "body": {
            "pmt_id": 1234567
        }
    }
}

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

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

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

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

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

Поле Тип Опис
response object Об'єкт відповіді
response.pmt_id integer ID платежу в системі iPay
response.status string CREATED, INPROCESS, ERROR

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

{
    "response": {
        "pmt_id": 1234567,
        "status": "INPROCESS"
    }
}

3.4.9 ProcessPayment

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

Поле Тип Опис
Обов'язкові поля
pmt_id integer ID платежу в системі iPay

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

{
    "request": {
        "version": 1.20,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "ProcessPayment",
        "body": {
            "pmt_id": 1234567
        }
    }
}

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

Поле Тип Опис
response object Об'єкт відповіді
response.pmt_id integer ID платежу в системі iPay
response.invoice integer Сума платежу, у копійках
response.amount integer Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status integer Статус платежу (4 - неуспішний, 5 - успішний)
response.card_mask string Маска картки
response.bank_response object Відповідь банку
response.bank_response.error_group integer Група помилки
response.bank_acquirer_name string Назва банка екваєра
response.rrn string RRN (повертається для статусу платежу - 3, 5)
response.terminal_id string|null ID терміналу (повертається для статусу платежу - 3, 5)
response.auth_code string Код авторізації (повертається для статусу платежу - 3, 5)
У випадку успішного платежу повертаються додаткові поля
response.recurrent_token string Токен рекурентного платежу, повертається якщо на запит PaymentCreate був переданий recurrent = true і платіж підтримує рекурент
response.mch_amount array Дані про зарахування Торговцю
response.mch_amount[].smch_id string Внутрішній ідентифікатор юридичної особи
response.mch_amount[].amount string Сума зарахування Торговцю в копійках

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280"
    }
}

3.5 Системні помилки

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

Поле Тип Опис
response object Об'єкт відповіді
response.error string Назва помилки

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

{
    "response": {
        "error": "invalid request structure"
    }
}
Назва помилки Опис
overall error Загальная помилка
invalid request structure Невірна структура запиту
invalid action Невідомий тип запиту
invalid token Не вдалося розшифрувати токен
invalid token format Токен повинен бути у форматі JSON
invalid token gatewayMerchantId Невідоме значення gatewayMerchantId
unknown field {field_name} Невідоме поле
invalid pan Невірний формат PAN картки
invalid expm Невірний формат місяця сроку дії картки
invalid expy Невірний формат року сроку дії картки
invalid cvv Невірний CVV код
invalid auth Помилка аутентифікації
invalid auth time Невірний час запиту
access denied Доступ заборонено

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

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

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 4,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}
Група помилки Опис
41 Відмова від банку-емітента
42 Недостатньо коштів
43 Ліміт банку-емітента
50 Неправильний CVV код
51 Помилка 3D Secure верифікації
52 Помилка зв'язку
55 Невідома помилка
56 Термін дії картки закінчився
57 Невірний номер картки
58 Ліміт на картці
60 Помилка 3D Secure верифікації
66 Операція відхилена через необхідність пройти 3DSecure верифікацію. Рекомендуємо повторно відправити запит, але з параметром pmt_info.force_security_rate=3D
67 Операція відхилена через те, що дана картка іноземного банку і заборонена для операції. Рекомендується зробити новий платіж з іншою платіжною картою.

© іPay.ua Товариство з обмеженою відповідальністю "Універсальні платіжні рішення"