Ipay ApplePay API v1.0.3

• Загальна інформація
• Доступи й налаштування
• PaymentToken
• Загальна структура запиту
• Перелік запитів
  1. Попередній розрахунок комісії
  2. Створити платіж
  3. Провести 3DS верифікацію платежу
  4. Завершити платіж
  5. Відмінити платіж
  6. Запросити квитанцію
  7. Статус платежу
  8. Отримати чек
• Інтеграція з Apple Pay Web
• Системні помилки
• Групи помилок

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

Даний сервіс дозволяє виконати списання коштів з картки доданої до ApplePay гаманця.

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

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

- login - ідентифікатор мерчанта

- sign_key - ключ для підпису

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

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

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

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

Приклад на PHP:

$ sign = hash(\'sha3-512\', \'2017-01-01 00:00:00\' . $ sign_key );

PaymentToken (передавання в запросі поля apple_data)

Обов\'язкові процедури для формування поля:

1. Потрібно надати запит до нас на формування CertificateSigningRequest.certSigningRequest в форматі (ecc 256)

2. Згенерувати у appleDev кабінеті PaymentProcessing.cert під мерчанта який вказаний в додатку.

3. Передати нам діючий сертифікат.

Після проведення цих процедур Ви будете отримувати відповідь від Apple, яку потрібно буде попередньо закодувати
в Base64, та передавати нам у полі apple_data в запросі PaymentCreate

Приклад відповіді у форматі JSON який получено від Apple

        
{

    "paymentData":{
        "version":"EC_v1",
        "data":"gvMXusr6e.....qB5qSlCzNv9Ugy",
        "signature":"MIAGCSq ..... 0dMx/d80r97Pf1MPxkhAAAAAAA",
        "header":{
            "ephemeralPublicKey":"MFkwEwYH.....SXc10Qt5NVkFjSRq8tk0dDw==",
            "publicKeyHash":"aVc7v.....qepG4=",
            "transactionId":"3e80774bbc385ec08a57e02acbf00fc74a3d032be84c42481e2cfc4f4446082b"
        }
    },
    "paymentMethod":{
        "displayName":"Visa 4655",
        "network":"Visa",
        "type":"debit"
    },
    "transactionIdentifier":"3E80774BBC385EC08A57E02ACBF00FC74A3D032BE84C42481E2CFC4F4446082B"

}
        
        

Цю відповідь потрібно закодувати у Base64 та передати у полі apple_data в запросі PaymentCreate

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

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

Поле	Тип	Опис
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.0.3,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "apple_data": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHVzcjZlWDE3WWFkNTduRmt5UUJoRkxOUUc4WmtSS3BUZlZuak12V0V0K2RmYVpnSUVnWmpJRzV3ODgzUWozbkNNQTBpaWVnSUpFbkNuNkJJakJPZ0dhRlFXSXN2YkNBVXFaUDMrOGF3QWFZRy9oYjFHNm1SOHY1cFlGdFNYOVU3UUVyajVMREFERlJ1Q05ZQlUvOFplc04rZG0vdkUwVDA2VkpydjhJRVR6Zm5BT3JIVDdqZ2hPTEVYVkNHNWN0SlVXL25aZUQrVFN4Y1BoMC93RTdMY3BIRDJQK09waks2dlZVL1A5UlB3cERoSXlQODBvNHNMbDI4L2xZS0gxb1hBZTYzTC8wL1Rrc1YzN0g5cFQ3b2NzOWhPNjFXcGViUDkxemk5VTNZOEdBZGxkZ2U0VG1hbDZTWTJacjNkWXNCbk5WTGt1RkNQNHlqOFd2Yjc4dFN1Z2tLaDFvZ3lGN24wRjNJQ2hZaDJTd0FvbmVRM1dGZWhRbThHaGRQNDZIUU5XbURMdm9KRG8vU0xrOE1EYlFhTytxQjVxU2xDek52OVVneSIsInNpZ25hdHVyZSI6Ik1JQUdDU3FHU0liM0RRRUhBcUNBTUlBQ0FRRXhEekFOQmdsZ2hrZ0JaUU1FQWdFRkFEQ0FCZ2txaGtpRzl3MEJCd0VBQUtDQU1JSUQ0akNDQTRpZ0F3SUJBZ0lJSkVQeXFBYWQ5WGN3Q2dZSUtvWkl6ajBFQXdJd2VqRXVNQ3dHQTFVRUF3d2xRWEJ3YkdVZ1FYQndiR2xqWVhScGIyNGdTVzUwWldkeVlYUnBiMjRnUTBFZ0xTQkhNekVtTUNRR0ExVUVDd3dkUVhCd2JHVWdRMlZ5ZEdsbWFXTmhkR2x2YmlCQmRYUm9iM0pwZEhreEV6QVJCZ05WQkFvTUNrRndjR3hsSUVsdVl5NHhDekFKQmdOVkJBWVRBbFZUTUI0WERURTBNRGt5TlRJeU1EWXhNVm9YRFRFNU1Ea3lOREl5TURZeE1Wb3dYekVsTUNNR0ExVUVBd3djWldOakxYTnRjQzFpY205clpYSXRjMmxuYmw5VlF6UXRVRkpQUkRFVU1CSUdBMVVFQ3d3TGFVOVRJRk41YzNSbGJYTXhFekFSQmdOVkJBb01Da0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRXdoVjM3ZXZXeDdJaGoyamRjSkNoSVkzSHNMMXZMQ2c5aEdDVjJVcjBwVUViZzBJTzJCSHpRSDZETXg4Y1ZNUDM2eklnMXJyVjFPLzBrb21KUG53UEU2T0NBaEV3Z2dJTk1FVUdDQ3NHQVFVRkJ3RUJCRGt3TnpBMUJnZ3JCZ0VGQlFjd0FZWXBhSFIwY0RvdkwyOWpjM0F1WVhCd2JHVXVZMjl0TDI5amMzQXdOQzFoY0hCc1pXRnBZMkV6TURFd0hRWURWUjBPQkJZRUZKUlgyMi9WZElHR2lZbDJMMzVYaFFmbm0xZ2tNQXdHQTFVZEV3RUIvd1FDTUFBd0h3WURWUjBqQkJnd0ZvQVVJL0pKeEUrVDVPOG41c1QyS0d3L29ydjlMa3N3Z2dFZEJnTlZIU0FFZ2dFVU1JSUJFRENDQVF3R0NTcUdTSWIzWTJRRkFUQ0IvakNCd3dZSUt3WUJCUVVIQWdJd2diWU1nYk5TWld4cFlXNWpaU0J2YmlCMGFHbHpJR05sY25ScFptbGpZWFJsSUdKNUlHRnVlU0J3WVhKMGVTQmhjM04xYldWeklHRmpZMlZ3ZEdGdVkyVWdiMllnZEdobElIUm9aVzRnWVhCd2JHbGpZV0pzWlNCemRHRnVaR0Z5WkNCMFpYSnRjeUJoYm1RZ1kyOXVaR2wwYVc5dWN5QnZaaUIxYzJVc0lHTmxjblJwWm1sallYUmxJSEJ2YkdsamVTQmhibVFnWTJWeWRHbG1hV05oZEdsdmJpQndjbUZqZEdsalpTQnpkR0YwWlcxbGJuUnpMakEyQmdnckJnRUZCUWNDQVJZcWFIUjBjRG92TDNkM2R5NWhjSEJzWlM1amIyMHZZMlZ5ZEdsbWFXTmhkR1ZoZFhSb2IzSnBkSGt2TURRR0ExVWRId1F0TUNzd0thQW5vQ1dHSTJoMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsWVdsallUTXVZM0pzTUE0R0ExVWREd0VCL3dRRUF3SUhnREFQQmdrcWhraUc5Mk5rQmgwRUFnVUFNQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJSEtLbncrU295cTVtWFFyMVY2MmMwQlhLcGFIb2RZdTlUV1hFUFVXUHBicEFpRUFrVGVjZlc2K1c1bDByMEFEZnpUQ1BxMll0YlMzOXcwMVhJYXlxQk55OGJFd2dnTHVNSUlDZGFBREFnRUNBZ2hKYlMrL09wamFsekFLQmdncWhrak9QUVFEQWpCbk1Sc3dHUVlEVlFRRERCSkJjSEJzWlNCU2IyOTBJRU5CSUMwZ1J6TXhKakFrQmdOVkJBc01IVUZ3Y0d4bElFTmxjblJwWm1sallYUnBiMjRnUVhWMGFHOXlhWFI1TVJNd0VRWURWUVFLREFwQmNIQnNaU0JKYm1NdU1Rc3dDUVlEVlFRR0V3SlZVekFlRncweE5EQTFNRFl5TXpRMk16QmFGdzB5T1RBMU1EWXlNelEyTXpCYU1Ib3hMakFzQmdOVkJBTU1KVUZ3Y0d4bElFRndjR3hwWTJGMGFXOXVJRWx1ZEdWbmNtRjBhVzl1SUVOQklDMGdSek14SmpBa0JnTlZCQXNNSFVGd2NHeGxJRU5sY25ScFptbGpZWFJwYjI0Z1FYVjBhRzl5YVhSNU1STXdFUVlEVlFRS0RBcEJjSEJzWlNCSmJtTXVNUXN3Q1FZRFZRUUdFd0pWVXpCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQlBBWEVZUVoxMlNGMVJwZUpZRUhkdWlBb3UvZWU2NU40STM4UzVQaE0xYlZabHMxcmlMUWwzWU5JazU3dWdqOWRoZk9pTXQydTJad3Zzam9LWVQvVkVXamdmY3dnZlF3UmdZSUt3WUJCUVVIQVFFRU9qQTRNRFlHQ0NzR0FRVUZCekFCaGlwb2RIUndPaTh2YjJOemNDNWhjSEJzWlM1amIyMHZiMk56Y0RBMExXRndjR3hsY205dmRHTmhaek13SFFZRFZSME9CQllFRkNQeVNjUlBrK1R2SitiRTlpaHNQNks3L1M1TE1BOEdBMVVkRXdFQi93UUZNQU1CQWY4d0h3WURWUjBqQkJnd0ZvQVV1N0Rlb1ZnemlKcWtpcG5ldnIzcnI5ckxKS3N3TndZRFZSMGZCREF3TGpBc29DcWdLSVltYUhSMGNEb3ZMMk55YkM1aGNIQnNaUzVqYjIwdllYQndiR1Z5YjI5MFkyRm5NeTVqY213d0RnWURWUjBQQVFIL0JBUURBZ0VHTUJBR0NpcUdTSWIzWTJRR0FnNEVBZ1VBTUFvR0NDcUdTTTQ5QkFNQ0EyY0FNR1FDTURyUGNvTlJGcG14aHZzMXcxYktZci8wRiszWkQzVk5vbzYrOFp5QlhrSzNpZmlZOTV0Wm41alZRUTJQbmVuQy9nSXdNaTNWUkNHd293VjNiRjN6T0R1UVovMFhmQ3doYlpaUHhuSnBnaEp2VlBoNmZSdVp5NXNKaVNGaEJwa1BDWklkQUFBeGdnR01NSUlCaUFJQkFUQ0JoakI2TVM0d0xBWURWUVFERENWQmNIQnNaU0JCY0hCc2FXTmhkR2x2YmlCSmJuUmxaM0poZEdsdmJpQkRRU0F0SUVjek1TWXdKQVlEVlFRTERCMUJjSEJzWlNCRFpYSjBhV1pwWTJGMGFXOXVJRUYxZEdodmNtbDBlVEVUTUJFR0ExVUVDZ3dLUVhCd2JHVWdTVzVqTGpFTE1Ba0dBMVVFQmhNQ1ZWTUNDQ1JEOHFnR25mVjNNQTBHQ1dDR1NBRmxBd1FDQVFVQW9JR1ZNQmdHQ1NxR1NJYjNEUUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERURTVNREl3TlRFME1UZ3dNRm93S2dZSktvWklodmNOQVFrME1SMHdHekFOQmdsZ2hrZ0JaUU1FQWdFRkFLRUtCZ2dxaGtqT1BRUURBakF2QmdrcWhraUc5dzBCQ1FReElnUWdrcVhiV2lWUGI0KzIxWkg4Y2RGQVpISzJ3Y1M1cjhZc3l4L1p6YUpIbkdnd0NnWUlLb1pJemowRUF3SUVSekJGQWlFQTdjT3ZVK01QVHZMVnpmenJFckMwdGpJL1pCb2FsTmFiQWJUcWUvRFdzeVlDSUF5dTdGa1FZV0o4Z0doTW4wZE14L2Q4MHI5N1BmMU1QeGtobDlXVjNzNjdBQUFBQUFBQSIsImhlYWRlciI6eyJlcGhlbWVyYWxQdWJsaWNLZXkiOiJNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUVzaFhkdFl2dE5RL2JoNEJSWnZXQmM5Mk5aeUlYR0ltbU9PN0xoY0V4SG94YTZMS3U1aXhLZEpEcGx6cDNyTXJTWGMxMFF0NU5Wa0ZqU1JxOHRrMGREdz09IiwicHVibGljS2V5SGFzaCI6ImFWYzd2UTRTTzEyUnVEWUlyajhOT25zL05ncUJYZm1EaWE1ZmZKcWVwRzQ9IiwidHJhbnNhY3Rpb25JZCI6IjNlODA3NzRiYmMzODVlYzA4YTU3ZTAyYWNiZjAwZmM3NGEzZDAzMmJlODRjNDI0ODFlMmNmYzRmNDQ0NjA4MmIifX0sInBheW1lbnRNZXRob2QiOnsiZGlzcGxheU5hbWUiOiJWaXNhIDQ2NTUiLCJuZXR3b3JrIjoiVmlzYSIsInR5cGUiOiJkZWJpdCJ9LCJ0cmFuc2FjdGlvbklkZW50aWZpZXIiOiIzRTgwNzc0QkJDMzg1RUMwOEE1N0UwMkFDQkYwMEZDNzRBM0QwMzJCRTg0QzQyNDgxRTJDRkM0RjQ0NDYwODJCIn0=",
            "pmt_desc": "Тестовий платіж",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "ext_id": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}    
            

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

1. CalculateFee (Попередній розрахунок комісії)

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

Поле	Тип	Опис
Обов\'язкові поля
invoice	string	Сума платежу, у копійках
Опціональні поля
msisdn	string	Номер телефону
transactions	array	Масив транзакцій
transactions[].smch_id	array	ID юридичної особи
transactions[].invoice	array	Сума

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

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

Приклад запиту (масив транзакцій)

{
    "request": {
        "version": 1.0.3,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "CalculateFee",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "transactions": [
                {"smch_id": 123456, "invoice": 100}
            ]
        }
    }
}    
            

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

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

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

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

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

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

Поле	Тип	Опис
Обов\'язкові поля
invoice	string	Сума платежу, у копійках
apple_data	string	PaymentToken ApplePay у форматі JSON закодований в Base64
pmt_desc	string	Опис платежу
pmt_info	object	Інформація до платежу, надається мерчантом при створенні, якщо присутнє значення (integer) smch_id - буде обиратись зазначена юридична особа
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_accept_header	string	Точне значення HTTP заголовків, відправлених з браузера користувача на сайт, на якому виконується оплата
threeds_info.browser_tz	string	Зміщення часового поясу між Гринвічем та місцевим часом користувача, в хвилинах, наприклад "-120" для часового поясу Europe/Kiev
threeds_info.browser_user_agent	string	Точний зміст HTTP заголовка user-agent
Опціональні поля
msisdn	string	Номер телефону
ext_id	string	Унікальний ідентифікатор оплати в системні мерчанта (максимальна довжина - 50 символів)
transactions	array	Масив транзакцій. Дозволяє розщепити платіж на декілька отримувачів коштів.
transactions[].invoice	integer	Сума транзакції, у копійках
transactions[].smch_id	integer	ID отримувача коштів, надається iPay
transactions[].desc	string	Призначення платежу, надається мерчантом при створенні (у форматі текст до 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": {
        "version": 1.0.3,
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "apple_data": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHVzcjZlWDE3WWFkNTduRmt5UUJoRkxOUUc4WmtSS3BUZlZuak12V0V0K2RmYVpnSUVnWmpJRzV3ODgzUWozbkNNQTBpaWVnSUpFbkNuNkJJakJPZ0dhRlFXSXN2YkNBVXFaUDMrOGF3QWFZRy9oYjFHNm1SOHY1cFlGdFNYOVU3UUVyajVMREFERlJ1Q05ZQlUvOFplc04rZG0vdkUwVDA2VkpydjhJRVR6Zm5BT3JIVDdqZ2hPTEVYVkNHNWN0SlVXL25aZUQrVFN4Y1BoMC93RTdMY3BIRDJQK09waks2dlZVL1A5UlB3cERoSXlQODBvNHNMbDI4L2xZS0gxb1hBZTYzTC8wL1Rrc1YzN0g5cFQ3b2NzOWhPNjFXcGViUDkxemk5VTNZOEdBZGxkZ2U0VG1hbDZTWTJacjNkWXNCbk5WTGt1RkNQNHlqOFd2Yjc4dFN1Z2tLaDFvZ3lGN24wRjNJQ2hZaDJTd0FvbmVRM1dGZWhRbThHaGRQNDZIUU5XbURMdm9KRG8vU0xrOE1EYlFhTytxQjVxU2xDek52OVVneSIsInNpZ25hdHVyZSI6Ik1JQUdDU3FHU0liM0RRRUhBcUNBTUlBQ0FRRXhEekFOQmdsZ2hrZ0JaUU1FQWdFRkFEQ0FCZ2txaGtpRzl3MEJCd0VBQUtDQU1JSUQ0akNDQTRpZ0F3SUJBZ0lJSkVQeXFBYWQ5WGN3Q2dZSUtvWkl6ajBFQXdJd2VqRXVNQ3dHQTFVRUF3d2xRWEJ3YkdVZ1FYQndiR2xqWVhScGIyNGdTVzUwWldkeVlYUnBiMjRnUTBFZ0xTQkhNekVtTUNRR0ExVUVDd3dkUVhCd2JHVWdRMlZ5ZEdsbWFXTmhkR2x2YmlCQmRYUm9iM0pwZEhreEV6QVJCZ05WQkFvTUNrRndjR3hsSUVsdVl5NHhDekFKQmdOVkJBWVRBbFZUTUI0WERURTBNRGt5TlRJeU1EWXhNVm9YRFRFNU1Ea3lOREl5TURZeE1Wb3dYekVsTUNNR0ExVUVBd3djWldOakxYTnRjQzFpY205clpYSXRjMmxuYmw5VlF6UXRVRkpQUkRFVU1CSUdBMVVFQ3d3TGFVOVRJRk41YzNSbGJYTXhFekFSQmdOVkJBb01Da0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRXdoVjM3ZXZXeDdJaGoyamRjSkNoSVkzSHNMMXZMQ2c5aEdDVjJVcjBwVUViZzBJTzJCSHpRSDZETXg4Y1ZNUDM2eklnMXJyVjFPLzBrb21KUG53UEU2T0NBaEV3Z2dJTk1FVUdDQ3NHQVFVRkJ3RUJCRGt3TnpBMUJnZ3JCZ0VGQlFjd0FZWXBhSFIwY0RvdkwyOWpjM0F1WVhCd2JHVXVZMjl0TDI5amMzQXdOQzFoY0hCc1pXRnBZMkV6TURFd0hRWURWUjBPQkJZRUZKUlgyMi9WZElHR2lZbDJMMzVYaFFmbm0xZ2tNQXdHQTFVZEV3RUIvd1FDTUFBd0h3WURWUjBqQkJnd0ZvQVVJL0pKeEUrVDVPOG41c1QyS0d3L29ydjlMa3N3Z2dFZEJnTlZIU0FFZ2dFVU1JSUJFRENDQVF3R0NTcUdTSWIzWTJRRkFUQ0IvakNCd3dZSUt3WUJCUVVIQWdJd2diWU1nYk5TWld4cFlXNWpaU0J2YmlCMGFHbHpJR05sY25ScFptbGpZWFJsSUdKNUlHRnVlU0J3WVhKMGVTQmhjM04xYldWeklHRmpZMlZ3ZEdGdVkyVWdiMllnZEdobElIUm9aVzRnWVhCd2JHbGpZV0pzWlNCemRHRnVaR0Z5WkNCMFpYSnRjeUJoYm1RZ1kyOXVaR2wwYVc5dWN5QnZaaUIxYzJVc0lHTmxjblJwWm1sallYUmxJSEJ2YkdsamVTQmhibVFnWTJWeWRHbG1hV05oZEdsdmJpQndjbUZqZEdsalpTQnpkR0YwWlcxbGJuUnpMakEyQmdnckJnRUZCUWNDQVJZcWFIUjBjRG92TDNkM2R5NWhjSEJzWlM1amIyMHZZMlZ5ZEdsbWFXTmhkR1ZoZFhSb2IzSnBkSGt2TURRR0ExVWRId1F0TUNzd0thQW5vQ1dHSTJoMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsWVdsallUTXVZM0pzTUE0R0ExVWREd0VCL3dRRUF3SUhnREFQQmdrcWhraUc5Mk5rQmgwRUFnVUFNQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJSEtLbncrU295cTVtWFFyMVY2MmMwQlhLcGFIb2RZdTlUV1hFUFVXUHBicEFpRUFrVGVjZlc2K1c1bDByMEFEZnpUQ1BxMll0YlMzOXcwMVhJYXlxQk55OGJFd2dnTHVNSUlDZGFBREFnRUNBZ2hKYlMrL09wamFsekFLQmdncWhrak9QUVFEQWpCbk1Sc3dHUVlEVlFRRERCSkJjSEJzWlNCU2IyOTBJRU5CSUMwZ1J6TXhKakFrQmdOVkJBc01IVUZ3Y0d4bElFTmxjblJwWm1sallYUnBiMjRnUVhWMGFHOXlhWFI1TVJNd0VRWURWUVFLREFwQmNIQnNaU0JKYm1NdU1Rc3dDUVlEVlFRR0V3SlZVekFlRncweE5EQTFNRFl5TXpRMk16QmFGdzB5T1RBMU1EWXlNelEyTXpCYU1Ib3hMakFzQmdOVkJBTU1KVUZ3Y0d4bElFRndjR3hwWTJGMGFXOXVJRWx1ZEdWbmNtRjBhVzl1SUVOQklDMGdSek14SmpBa0JnTlZCQXNNSFVGd2NHeGxJRU5sY25ScFptbGpZWFJwYjI0Z1FYVjBhRzl5YVhSNU1STXdFUVlEVlFRS0RBcEJjSEJzWlNCSmJtTXVNUXN3Q1FZRFZRUUdFd0pWVXpCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQlBBWEVZUVoxMlNGMVJwZUpZRUhkdWlBb3UvZWU2NU40STM4UzVQaE0xYlZabHMxcmlMUWwzWU5JazU3dWdqOWRoZk9pTXQydTJad3Zzam9LWVQvVkVXamdmY3dnZlF3UmdZSUt3WUJCUVVIQVFFRU9qQTRNRFlHQ0NzR0FRVUZCekFCaGlwb2RIUndPaTh2YjJOemNDNWhjSEJzWlM1amIyMHZiMk56Y0RBMExXRndjR3hsY205dmRHTmhaek13SFFZRFZSME9CQllFRkNQeVNjUlBrK1R2SitiRTlpaHNQNks3L1M1TE1BOEdBMVVkRXdFQi93UUZNQU1CQWY4d0h3WURWUjBqQkJnd0ZvQVV1N0Rlb1ZnemlKcWtpcG5ldnIzcnI5ckxKS3N3TndZRFZSMGZCREF3TGpBc29DcWdLSVltYUhSMGNEb3ZMMk55YkM1aGNIQnNaUzVqYjIwdllYQndiR1Z5YjI5MFkyRm5NeTVqY213d0RnWURWUjBQQVFIL0JBUURBZ0VHTUJBR0NpcUdTSWIzWTJRR0FnNEVBZ1VBTUFvR0NDcUdTTTQ5QkFNQ0EyY0FNR1FDTURyUGNvTlJGcG14aHZzMXcxYktZci8wRiszWkQzVk5vbzYrOFp5QlhrSzNpZmlZOTV0Wm41alZRUTJQbmVuQy9nSXdNaTNWUkNHd293VjNiRjN6T0R1UVovMFhmQ3doYlpaUHhuSnBnaEp2VlBoNmZSdVp5NXNKaVNGaEJwa1BDWklkQUFBeGdnR01NSUlCaUFJQkFUQ0JoakI2TVM0d0xBWURWUVFERENWQmNIQnNaU0JCY0hCc2FXTmhkR2x2YmlCSmJuUmxaM0poZEdsdmJpQkRRU0F0SUVjek1TWXdKQVlEVlFRTERCMUJjSEJzWlNCRFpYSjBhV1pwWTJGMGFXOXVJRUYxZEdodmNtbDBlVEVUTUJFR0ExVUVDZ3dLUVhCd2JHVWdTVzVqTGpFTE1Ba0dBMVVFQmhNQ1ZWTUNDQ1JEOHFnR25mVjNNQTBHQ1dDR1NBRmxBd1FDQVFVQW9JR1ZNQmdHQ1NxR1NJYjNEUUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERURTVNREl3TlRFME1UZ3dNRm93S2dZSktvWklodmNOQVFrME1SMHdHekFOQmdsZ2hrZ0JaUU1FQWdFRkFLRUtCZ2dxaGtqT1BRUURBakF2QmdrcWhraUc5dzBCQ1FReElnUWdrcVhiV2lWUGI0KzIxWkg4Y2RGQVpISzJ3Y1M1cjhZc3l4L1p6YUpIbkdnd0NnWUlLb1pJemowRUF3SUVSekJGQWlFQTdjT3ZVK01QVHZMVnpmenJFckMwdGpJL1pCb2FsTmFiQWJUcWUvRFdzeVlDSUF5dTdGa1FZV0o4Z0doTW4wZE14L2Q4MHI5N1BmMU1QeGtobDlXVjNzNjdBQUFBQUFBQSIsImhlYWRlciI6eyJlcGhlbWVyYWxQdWJsaWNLZXkiOiJNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUVzaFhkdFl2dE5RL2JoNEJSWnZXQmM5Mk5aeUlYR0ltbU9PN0xoY0V4SG94YTZMS3U1aXhLZEpEcGx6cDNyTXJTWGMxMFF0NU5Wa0ZqU1JxOHRrMGREdz09IiwicHVibGljS2V5SGFzaCI6ImFWYzd2UTRTTzEyUnVEWUlyajhOT25zL05ncUJYZm1EaWE1ZmZKcWVwRzQ9IiwidHJhbnNhY3Rpb25JZCI6IjNlODA3NzRiYmMzODVlYzA4YTU3ZTAyYWNiZjAwZmM3NGEzZDAzMmJlODRjNDI0ODFlMmNmYzRmNDQ0NjA4MmIifX0sInBheW1lbnRNZXRob2QiOnsiZGlzcGxheU5hbWUiOiJWaXNhIDQ2NTUiLCJuZXR3b3JrIjoiVmlzYSIsInR5cGUiOiJkZWJpdCJ9LCJ0cmFuc2FjdGlvbklkZW50aWZpZXIiOiIzRTgwNzc0QkJDMzg1RUMwOEE1N0UwMkFDQkYwMEZDNzRBM0QwMzJCRTg0QzQyNDgxRTJDRkM0RjQ0NDYwODJCIn0=",
            "pmt_desc": "Тестовий платіж",
            "pmt_info": {
                "custom_merchant_field": 1234567,
                "smch_id": 112233
            },
            "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"
            }
        }
    }
}    
            

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

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

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

Поле	Тип	Опис
response	object	Тіло відповіді
response.pmt_id	string	ID платежу в системі iPay
response.invoice	string	Сума платежу, у копійках
response.amount	string	Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status	string	Статус платежу (1 - верифікація платежу, 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
response.auth_code	string	Код авторізації
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":"4",
        "card_mask":"****************",
        "bank_response": {
            "error_group":12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}
            

Приклад відповіді (3DS верифікація)

{
    "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": "АТ «Ощадбанк»"
    }
}
        

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

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

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

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

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

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

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

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

Поле	Тип	Опис
response	object	Тіло відповіді
response.pmt_id	string	ID платежу в системі iPay
response.invoice	string	Сума платежу, у копійках
response.amount	string	Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status	string	Статус платежу (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
response.auth_code	string	Код авторізації
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":"4",
        "card_mask":"****************",
        "bank_response":{
            "error_group":12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

4. PaymentSale (Завершити платіж)

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

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

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

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

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

{
    "request": {
        "version": 1.0.3,
        "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	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
response.auth_code	string	Код авторізації
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":"4",
        "card_mask":"****************",
        "bank_response":{
            "error_group":12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

5. PaymentCancel (Відмінити платіж)

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

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

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

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

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

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

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

{
    "response": {
        "pmt_id":"1234567",
        "invoice":"100",
        "amount":"100",
        "pmt_status":"9",
        "card_mask":"****************",
        "bank_response":{
            "error_group":12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

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

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

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

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

{
    "request":{
        "version": 1.0.3,
        "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"
    }
}

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

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

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

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

{
    "request":{
        "version": 1.0.3,
        "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	Статус платежу (1 - верифікація платежу, 3 - кошти успішно заблоковані, 4 - неуспішний, 5 - успішний, 9 - відмінений)
response.card_mask	string	Маска картки
response.bank_response	object	Відповідь банку
response.bank_response.error_group	integer	Група помилки
response.bank_acquirer_name	string	Назва банка екваєра

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

{
    "response": {
        "pmt_id":"1234567",
        "invoice":"100",
        "amount":"100",
        "pmt_status":"9",
        "card_mask":"****************",
        "bank_response":{
            "error_group":12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

8. GetReceipt (Отримати чек)

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

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

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

{
    "request": {
        "version": 1.0.3,
        "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	string	ID платежу в системі iPay
response.status	string	CREATED, INPROCESS, ERROR

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

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

Інтеграція з Apple Pay Web

Попередні умови :

1. Ваш сайт повинен працювати за схемою HTTPS і підтримувати протокол TLS 1.2.

2. Потрібно погодитись з умовами надання послуг Apple Pay.

3. Необхідно укласти договір з Ipay.ua

Інтеграції Apple Pay на сайт :

1. Необхідно мати аккаунт в Apple Developer

2. Додайте новий Merchant ID в Apple Developer Account

• Оберіть створений вами Merchant ID та натисніть «Edit».
• У розділі «Merchant Domains» натисніть «Add Domain».
• Зареєструйте та підтвердьте свій домен

3. Створіть Apple Pay Merchant Identity Certificate:

• У розділі «Apple Pay Merchant Identity Certificate» натисніть «Create Certificate»
• Виконайте дії, описані на сайті Apple, а потім натисніть «Continue».
• Скопіюйте створений сертифікат у форматі .pem на сервер. Це буде необхідно для створення Apple Pay Payment Session в процесі перевірки магазину.

3. Створіть Apple Pay Payment processing certificate :
developer.apple.com/documentation/passkit/apple_pay/setting_up_apple_pay_requirements

• Запросити у відповідального менеджера CSR-файл, сформований Ipay.ua
• Сформуйте Apple Pay Payment Processing Certificate та передайте його відповідальному менеджеру

Технічна інтеграція з ApplePay

Щоб інтегрувати Apple Pay на сайт, дотримуйтесь інструкцій за посиланням:
https://developer.apple.com/documentation/apple_pay_on_the_web

Перевірте можливість оплати з Apple Pay

        if(window.ApplePaySession && window.ApplePaySession.canMakePayments() ){
      
        var merchantIdentifier=\'{YourMchName}\';
        var  promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
        promise.then(function (canMakePayments) {
            if (canMakePayments){
            }
         });
    }
});      
       

Обробка кліка по кнопці ApplePay

       function applePayButtonClick() {

     var merchantID = \'{YourMchName}\';

     var  session= new ApplePaySession(3,createPaymentRequest());

      session.begin();

     session.onvalidatemerchant = (event) => {

         const validationURL = event.validationURL;
         
         var promise = performValidation(event.validationURL);
         
         promise.then(function (merchantSession) {
             session.completeMerchantValidation(merchantSession);
         });

     };

     session.onpaymentauthorized = function (event) {

         if (event.payment.token) {
         
          //event.payment.token  (Токен який треба передаты до  Ipay.ua)
         
             session.completePayment(ApplePaySession.STATUS_SUCCESS);
         } else {
             session.completePayment(ApplePaySession.STATUS_FAILURE);
            
         }


     };
 }
       
       

Створення інформації платежу

developer.apple.com/documentation/apple_pay_on_the_web/applepayrequest

          
          function createPaymentRequest() {

        var request = {
            "countryCode": "UA",
            "currencyCode": "UAH",
            "merchantCapabilities": [
                "supports3DS"
            ],
            "supportedNetworks": [
                "visa",
                "masterCard"
            ],
            "total": {
                "label": "{yourLabel}",
                "type": "final",
                "amount": "{yourAmount}"
            }
        };

        return request;
    }
          
          

Запит на Ваш сервер для отримання об\'єкта сесії

developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/requesting_an_apple_pay_payment_session

       function performValidation(valURL) {


    return new Promise(function(resolve, reject) {

        var body=\'url=\'+valURL;
        var xhr = new XMLHttpRequest();
        xhr.onload = function() {

            var data = JSON.parse(this.responseText);

            resolve(data);
        };
        xhr.onerror = reject;
        xhr.open(\'POST\',\'{yourUrlForGetAppleSession}\',true);
        xhr.setRequestHeader(\'Content-Type\', \'application/x-www-form-urlencoded\');
        xhr.send(body);
    });
}
       
       

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

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

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

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

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

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

Помилка	Опис
overall error	Загальна помилка
invalid request structure	Невірна структура запиту
unknown field {field_name}	У запиті передано поле, яке невідоме системі
invalid pan	Невірне значення pan
invalid expm	Невірне значення expm
invalid expy	Невірне значення expy
invalid cvv	Невірне значення cvv
invalid auth	Помилка аутентифікації
invalid auth time	Невірний час запиту
access denied	Доступ заборонено

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

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

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

{  
    "response":{  
        "pmt_id":"1234567",
        "invoice":"100",
        "amount":"100",
        "pmt_status":"4",
        "card_mask":"****************",
        "bank_response": {
            "error_group":12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

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

Група помилки	Опис
41	Відмова емітента
42	Недостатньо коштів
43	Ліміт емітента
50	Невірний CVV
51	Помилка верифікації (3D Secure)
52	Помилка з\'єднання
55	Невідома помилка
56	Термін дії картки закінчився
57	Невірний номер картки
58	Ліміт на картці
60	Помилка верифікації (3D Secure)

Історія змін

Дата	Версія	Опис змін
2019-02-10	1.0.0	Налаштування запитів PaymentCreate, PaymentSale.
2019-04-04	1.0.1	Додано запит CalculateFee - розрахунок коміссії перед створенням платежу. PaymentCreate - у pmt_info опис переданого значення smch_id PaymentSale - invoice переведений в опціональне поле
2021-10-25	1.0.2	Додано запит PaymentVerify3DS - підтвердження результатів проходження 3D Secure. PaymentCreate - у запит додано поле threeds_info з параметрами для проходженная 3D Secure. PaymentCreate - у відповідь додано поля security_rate та security_data.
2021-11-05	1.0.2	В запит CalculateFee додана можливість передачі масива транзакцій для розрахунку комісії.
2023-07-07	1.0.3	В базову структуру запиту додано можливість передавати версію API - поле "version". В запит PaymentSale додано можливість передавати транзакції. В запит PaymentCreate додано можливість передавати ext_id (унікальний ідентифікатор оплати в системі мерчанта)