Перейти к содержанию

Виплати

Методи і сервіси для виплат

Для отримання списку доступних методів для проведення операції використовуються передзапити.

Передзапит передбачає фільтрацію сервісів за ініційованою сумою та вилучення з них методів для відображення на сторінці.

API: PUBLIC

Авторизація: Public keys

Endpoint: /payout-prerequest

Method: POST

Приклади (JSON)
{
"currency":"UAH",
"amount":10,
"public_key":"pk_test_NM6Rpg6A29zNlSQHiCsprOJyT9WXuFa76WcwwBB69cS"
}
{
    "data":{
        "currency":"UAH",
        "amount":10,
        "test_mode":true,
        "services":{
            "test_uah":{
                "code":"test_uah",
                "method":"test",
                "currency":"UAH",
                "fields":[
                {
                    "key":"account",
                    "type":"string",
                    "label":{
                        "ru":"Аккаунт",
                        "en":"Account",
                        "uk":"Акаунт"
                    },
                    "example":null,
                    "hint":{
                        "ru":"Аккаунт",
                        "en":"Account",
                        "uk":"Акаунт"
                    },
                    "regexp":"^\\\\d{1,15}$",
                    "required":true,
                    "position":0
                },
                {
                    "key":"test_details_success_rate",
                    "type":"string",
                    "label":{
                        "ru":"Вероятность успеха (%)",
                        "en":"Success rate (%)",
                        "uk":"Імовірність успіху (%)"
                    },
                    "example":null,
                    "hint":{
                        "ru":"Вероятность успеха (%)",
                        "en":"Success rate (%)",
                        "uk":"Імовірність успіху (%)"
                    },
                    "regexp":"^\\\\d{1,15}$",
                    "required":false,
                    "position":0
                },
                {
                    "key":"test_details_payout_status",
                    "type":"string",
                    "label":{
                        "ru":"Ожидаемый статус",
                        "en":"Expected status",
                        "uk":"Очікуваний статус"
                    },
                    "example":null,
                    "hint":{
                        "ru":"Ожидаемый статус",
                        "en":"Expected status",
                        "uk":"Очікуваний статус"
                    },
                    "regexp":"^[A-Z\\\\-\\\\sa-z]{2,64}$",
                    "required":false,
                    "position":0
                },
                {
                    "key":"test_details_payout_resolution",
                    "type":"string",
                    "label":{
                        "ru":"Ожидаемый resolution",
                        "en":"Expected resolution",
                        "uk":"Очікуваний resolution"
                    },
                    "example":null,
                    "hint":{
                        "ru":"Ожидаемый resolution",
                        "en":"Expected resolution",
                        "uk":"Очікуваний resolution"
                    },
                    "regexp":"^[A-Z\\\\-\\\\sa-z]{2,64}$",
                    "required":false,
                    "position":0
                }
                ],
                "amount_min":0.01,
                "amount_max":9999999,
                "exchange_rate":1,
                "amount":"10.00"
            },
            "methods":{
                "test":{
                "code":"test",
                "category":"alternative",
                "description":"",
                "name":{
                    "en":"Test",
                    "ru":"Test",
                    "uk":"Test"
                },
                "logo":"https://static.openfintech.io/payout_methods/test/logo.png",
                "icon":"https://static.openfintech.io/payout_methods/test/icon.svg",
                "metadata":null,
                "position":null,
                "hide":null
                }
            },
            "account":{
                "name":"4Docs",
                "description":"for documenting and testing",
                "icon":"https://static-dev.psp.name/images/default.svg?1595852370",
                "website":"https://lets.doc.it"
            }
        }
    }
}

Отримання списку доступних сервісів

Повний список сервісів

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payout-services

Method: GET

Приклад відповіді (JSON)
{
    "meta":{
        "total":168,
        "pages":9,
        "page":1
    },
    "links":{
        "first":"/api/payout-services?page[number]=1&page[size]=20",
        "next":"/api/payout-services?page[number]=2&page[size]=20",
        "last":"/api/payout-services?page[number]=9&page[size]=20"
    },
    "data":[
        {
            "type":"payout-services",
            "id":"comcpos_RHUGUgEnmmedR7h3",
            "attributes":{
                "service":"swift_uah",
                "service_method":"swift",
                "service_currency":"UAH",
                "available":true,
                "active":false,
                "enabled":true,
                "amount_min":1,
                "amount_max":999999,
                "fee_min":0,
                "fee_max":0,
                "fee_rate":0,
                "fee_fix":0,
                "currency":"UAH",
                "test_mode":true
            },
            "relationships":{
                "payout-method":{
                "data":{
                    "type":"payout-methods",
                    "id":"swift"
                }
                },
                "payout-service":{
                "data":{
                    "type":"payout-services",
                    "id":"swift_uah"
                }
                }
            },
            "links":{
                "self":"/api/payout-services/comcpos_RHUGUgEnmmedR7h3"
            }
        },
        {
            "type":"payout-services",
            "id":"comcpos_giKmqeYwcuWV4QSt",
            "attributes":{
                "service":"bank_transfer_zar",
                "service_method":"bank_transfer",
                "service_currency":"ZAR",
                "available":true,
                "active":false,
                "enabled":true,
                "amount_min":0.01,
                "amount_max":1000000,
                "fee_min":0,
                "fee_max":0,
                "fee_rate":0,
                "fee_fix":0,
                "currency":"UAH",
                "test_mode":true
            },
            "relationships":{
                "payout-method":{
                    "data":{
                        "type":"payout-methods",
                        "id":"bank_transfer"
                    }
                }
            }
        }
    ]
}

Дані сервісу за ID

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payout-services/{id}, де id взятий з минулого запиту

Method: GET

Приклад відповіді (JSON)
{
    "data": {
        "type": "payout-services",
        "id": "comcpos_RHUGUgEnmmedR7h3",
        "attributes": {
            "service": "swift_uah",
            "service_method": "swift",
            "service_currency": "UAH",
            "available": true,
            "active": false,
            "enabled": true,
            "amount_min": 1,
            "amount_max": 999999,
            "fee_min": 0,
            "fee_max": 0,
            "fee_rate": 0,
            "fee_fix": 0,
            "currency": "UAH",
            "test_mode": true
        },
        "relationships": {
            "payout-method": {
                "data": {
                    "type": "payout-methods",
                    "id": "swift"
                }
            },
            "payout-service": {
                "data": {
                    "type": "payout-services",
                    "id": "swift_uah"
                }
            }
        },
        "links": {
            "self": "/api/payout-services/comcpos_RHUGUgEnmmedR7h3"
        }
    }
}

Ініціювання відповіді

Зверніть увагу

Виплати ініціюються лише через приватний API.

Створення інвойсу

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payout-invoices

Method: POST

Обов'язкові поля:

  • reference_id - унікальний ідентифікатор операції на боці мерчанта
  • service - ідентифікатор сервісу, наприклад payment_card_UAH. Список усіх доступних сервісів можна переглянути в особистому кабінеті
  • currency - валюта виплати
  • amount / service_amount - сума платежу у валюті акаунту / сервісу
  • fields - (залежить від обов'язкових параметрів сервісу, в якому здійснюється виплата)

Додаткові поля:

  • callback_url - Callback URL для отримання повідомлень про зміну статусу інвойсу: замінює собою параметр Callback URL, заданий для облікового запису
  • context - додаткові параметри контексту одержувача. Наприклад: IP, Cardholder, Card expiry date. Деякі провайдери вимагають їх для додаткової перевірки
  • description - призначення платежу
  • options - параметри процесингу виплат. Необхідно уточнювати опції, доступні для облікового запису та логіку їхньої роботи
  • customer - об'єкт, який містить базові дані клієнта та будь-які пов'язані з ним метадані
    • reference_id - обов'язковий атрибут за наявності об'єкта у запиті
    • name
    • email
    • phone
    • metadata

JSON

{
    "data":{
        "type":"payout-invoice",
        "attributes":{
            "service":"card",
            "currency":"UAH",
            "amount":10,
            "reference_id":"a5c22bfb-04c1-4dbf-8b46-9753bf1f6570",
            "test_mode":true,
            "description": "Payout Invoice Example",
            "fields":{
                "card_number":"5123817234060000"
            },
            "callback_url":"https://webhook.site/1192f6ef-71c9-4b80-b43b-133d8fe14677",
            "options":{
                "split_mode":false,
                "parallel_mode":false,
                "allow_partially":false,
                "auto_process":false
            },
            "customer":{
                "reference_id":"1203515",
                "email":"somename@domain.com",
                "name":"John Wick",
                "metadata":{
                "key1":"value1",
                "key2":"value2"
                }
            },
            "metadata":{
                "key":"value"
            }
        }
    }
}
{
    "data": {
        "type": "payout-invoices",
        "id": "cpoi_VdHYVxq4RsLEebAQ",
        "attributes": {
            "serial_number": "VdHYVxq4RsLEebAQ",
            "status": "created",
            "resolution": "ok",
            "amount": 10,
            "payout_amount": 10,
            "currency": "UAH",
            "service_currency": "UAH",
            "service_amount": 10,
            "service_payout_amount": 10,
            "reference_id": "ada8c01f-f5d4-4037-88f1-d222ee6497ad",
            "test_mode": true,
            "description": "Payout Invoice Example",
            "fee": 0,
            "writeoff": 10,
            "exchange_rate": 1,
            "processed": null,
            "processed_amount": null,
            "processed_fee": 0,
            "processed_writeoff": null,
            "metadata": {
                "key": "value"
            },
            "created": 1597835735,
            "updated": 1597835735,
            "fields": {
                "card_number": "512381******0000"
            },
            "callback_url": "https://webhook.site/1192f6ef-71c9-4b80-b43b-133d8fe14677",
            "source": "merchant_api",
            "callback_logs": []
        },
        "relationships": {
            "payout-service": {
                "data": {
                    "type": "payout-services",
                    "id": "card"
                }
            },
            "payout-method": {
                "data": {
                    "type": "payout-methods",
                    "id": "payment_card"
                }
            },
            "customer": {
                "data": {
                    "type": "customers",
                    "id": "cus_Tjhe1ufEB3kRrgWy"
                }
            }
        },
        "links": {
            "self": "/api/payout-invoices/cpoi_VdHYVxq4RsLEebAQ"
        }
    }
}

Процесинг виплати

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payout-invoices/{id}/process

Method: POST

Приклад відповіді (JSON)
{
    "data": {
        "type": "payout-invoices",
        "id": "cpoi_VdHYVxq4RsLEebAQ",
        "attributes": {
            "serial_number": "VdHYVxq4RsLEebAQ",
            "status": "created",
            "resolution": "ok",
            "amount": 10,
            "payout_amount": 10,
            "currency": "UAH",
            "service_currency": "UAH",
            "service_amount": 10,
            "service_payout_amount": 10,
            "reference_id": "ada8c01f-f5d4-4037-88f1-d222ee6497ad",
            "test_mode": true,
            "description": "Payout Invoice Example",
            "fee": 0,
            "writeoff": 10,
            "exchange_rate": 1,
            "processed": null,
            "processed_amount": null,
            "processed_fee": 0,
            "processed_writeoff": null,
            "metadata": {
                "key": "value"
            },
            "created": 1597835735,
            "updated": 1597835735,
            "fields": {
                "card_number": "512381******0000"
            },
            "callback_url": "https://webhook.site/1192f6ef-71c9-4b80-b43b-133d8fe14677",
            "source": "merchant_api",
            "callback_logs": []
        },
        "relationships": {
            "payout-service": {
                "data": {
                    "type": "payout-services",
                    "id": "card"
                }
            },
            "payout-method": {
                "data": {
                    "type": "payout-methods",
                    "id": "payment_card"
                }
            },
            "customer": {
                "data": {
                    "type": "customers",
                    "id": "cus_Tjhe1ufEB3kRrgWy"
                }
            }
        },
        "links": {
            "self": "/api/payout-invoices/cpoi_VdHYVxq4RsLEebAQ"
        }
    }
}

Отримання даних виплати за ID (Реконсиляція)

Note

Статуси інвойсів описані у Керівництвах. Коди стану HTTP, що використовуються API у відповідях на запити, описані нижче.

Через публічний API

Через публічний API не можна ініціювати та процесувати виплату, але можна отримати деталі операції.

API: PUBLIC

Авторизація: Public keys

Endpoint:

  • /payout-invoices/{id} — для пошуку по ID CASCAD
  • /payout-invoices?filter[reference_id]={reference_id} — для поиска по Reference ID (например, ID заказа)

Method: GET

Приклад відповіді (JSON)

{
    "data": {
        "id": "cpoi_VdHYVxq4RsLEebAQ",
        "serial_number": "VdHYVxq4RsLEebAQ",
        "created": 1597835735,
        "status": "processed",
        "resolution": "ok",
        "test_mode": true,
        "currency": "UAH",
        "amount": 10,
        "payout_amount": 10,
        "service": "card",
        "service_amount": 10,
        "service_payout_amount": 10,
        "service_method": "payment_card",
        "service_currency": "UAH",
        "processed": 1597835933,
        "processed_amount": 10
    }
}

Через приватний API

API: PRIVATE

Авторизація: BasicAuth

Endpoint:

  • /payout-invoices/{id} — для поиска по ID CASCAD
  • /payout-invoices?filter[reference_id]={reference_id} — для пошуку по Reference ID (например, ID заказа)

Method: GET

Приклад відповіді (JSON)

{
    "data": {
        "type": "payout-invoices",
        "id": "cpoi_VdHYVxq4RsLEebAQ",
        "attributes": {
            "serial_number": "VdHYVxq4RsLEebAQ",
            "status": "processed",
            "resolution": "ok",
            "amount": 10,
            "payout_amount": 10,
            "currency": "UAH",
            "service_currency": "UAH",
            "service_amount": 10,
            "service_payout_amount": 10,
            "reference_id": "ada8c01f-f5d4-4037-88f1-d222ee6497ad",
            "test_mode": true,
            "description": "Payout Invoice Example",
            "fee": 0,
            "writeoff": 10,
            "exchange_rate": 1,
            "processed": 1597835933,
            "processed_amount": 10,
            "processed_fee": 0,
            "processed_writeoff": 10,
            "metadata": {
                "key": "value"
            },
            "created": 1597835735,
            "updated": 1597835933,
            "fields": {
                "card_number": "512381******0000"
            },
            "callback_url": "https://webhook.site/1192f6ef-71c9-4b80-b43b-133d8fe14677",
            "source": "merchant_api",
            "callback_logs": []
        },
        "relationships": {
            "payout-service": {
                "data": {
                    "type": "payout-services",
                    "id": "card"
                }
            },
            "payout-method": {
                "data": {
                    "type": "payout-methods",
                    "id": "payment_card"
                }
            },
            "customer": {
                "data": {
                    "type": "customers",
                    "id": "cus_Tjhe1ufEB3kRrgWy"
                }
            }
        },
        "links": {
            "self": "/api/payout-invoices/cpoi_VdHYVxq4RsLEebAQ"
        }
    }
}

Отримання списку виплат

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payout-invoices

Method: GET

Приклад відповіді (JSON)
{
    "meta": {
        "count": 5,
        "size": 20,
        "before": "cpoi_WSvqrC4BztUHs5Ji",
        "after": "cpoi_S1zoJnT8x4iZ4oPr"
    },
    "links": {
        "prev": "",
        "next": ""
    },
    "data": [
        {
            "type": "payout-invoices",
            "id": "cpoi_S1zoJnT8x4iZ4oPr",
            "attributes": {
                "serial_number": "S1zoJnT8x4iZ4oPr",
                "status": "created",
                "resolution": "ok",
                "amount": 10,
                "payout_amount": 10,
                "currency": "UAH",
                "service_currency": "UAH",
                "service_amount": 10,
                "service_payout_amount": 10,
                "reference_id": "1c005c55-d345-4eef-960b-bd8db14256b2",
                "test_mode": true,
                "description": "Payout Invoice Example",
                "fee": 0,
                "writeoff": 10,
                "exchange_rate": 1,
                "processed": null,
                "processed_amount": null,
                "processed_fee": 0,
                "processed_writeoff": null,
                "metadata": {
                    "key": "value"
                },
                "created": 1595841808,
                "updated": 1595841808,
                "fields": {
                    "card_number": "512381******0000"
                },
                "callback_url": "https://webhook.site/1192f6ef-71c9-4b80-b43b-133d8fe14677",
                "source": "merchant_api"
            },
            "relationships": {
                "payout-service": {
                    "data": {
                        "type": "payout-services",
                        "id": "card"
                    }
                },
                "payout-method": {
                    "data": {
                        "type": "payout-methods",
                        "id": "payment_card"
                    }
                },
                "customer": {
                    "data": {
                        "type": "customers",
                        "id": "cus_Tjhe1ufEB3kRrgWy"
                    }
                }
            },
            "links": {
                "self": "/api/payout-invoices/cpoi_S1zoJnT8x4iZ4oPr"
            }
        },
        {
            "type": "payout-invoices",
            "id": "cpoi_O2aH69xK7mgwZUK1",
            "attributes": {
                "serial_number": "O2aH69xK7mgwZUK1",
                "status": "processed",
                "resolution": "ok",
                "amount": 10,
                "payout_amount": 10,
                "currency": "UAH",
                "service_currency": "UAH",
                "service_amount": 10,
                "service_payout_amount": 10,
                "reference_id": "a5c22bfb-04c1-4dbf-8b46-9753bf1f6570",
                "test_mode": true,
                "description": "Payout Invoice Example",
                "fee": 0,
                "writeoff": 10,
                "exchange_rate": 1,
                "processed": 1595854491,
                "processed_amount": 10,
                "processed_fee": 0,
                "processed_writeoff": 10,
                "metadata": {
                    "key": "value"
                },
                "created": 1595841296,
                "updated": 1595854491,
                "fields": {
                    "card_number": "512381******0000"
                },
                "callback_url": "https://webhook.site/1192f6ef-71c9-4b80-b43b-133d8fe14677",
                "source": "merchant_api"
            },
            "relationships": {
                "payout-service": {
                    "data": {
                        "type": "payout-services",
                        "id": "card"
                    }
                },
                "payout-method": {
                    "data": {
                        "type": "payout-methods",
                        "id": "payment_card"
                    }
                },
                "customer": {
                    "data": {
                        "type": "customers",
                        "id": "cus_Tjhe1ufEB3kRrgWy"
                    }
                }
            },
            "links": {
                "self": "/api/payout-invoices/cpoi_O2aH69xK7mgwZUK1"
            }
        }
    ]
}

HTTP коди відповідей

Приклади відповідей з кодами та описами помилок

{
    "errors": [
        {
            "status": "Unauthorized",
            "code": "401"
        }
    ]
}
{
    "errors": [
        {
            "status": "Not Found",
            "code": "404"
        }
    ]
}
{
    "errors": [
        {
            "status": "Method Not Allowed",
            "code": "405"
        }
    ]
}
{
    "errors": {
        "amount": "This value should be greater than 0."
    }
}
{
    "errors": [
        {
            "status": "internal_error",
            "code": "500",
            "title": "internal_error",
            "detail": "Internal server error."
        }
    ]
}

2xx Успішні

Код Опис
200 OK Запит виконано успішно
201 Created POST запит на створення інвойсу виконано успіщно

4xx Помилки на боці клієнта

Код Тип Опис Інструкції
400 Bad Request Транспортна Запит невалідної структури, сервер не може його обробити Необхідно запросити статус операції (якщо використано правильний метод, але на запит статусу отримано помилку 404, можна вважати запит неуспішним і повторити операцію)
401 Unauthorized Авторизації Для отримання запиту потрібна автентифікація Перевірити дані авторизації. Запит фінально невдалий. Операція не створилася на боці платформи (якщо помилка виникла під час створення, не за інших методів)
403 Forbidden Авторизації У клієнта немає прав доступу для виклика методу Перевірити дані авторизації. Запит фінально невдалий. Операція не створилася на боці платформи (якщо помилка виникла під час створення, не за інших методів)
404 Not Found Валідації Сервер неспроможна знайти запитуваний метод чи ресурс У запиті вказано некоректний метод чи операції не існує (за коректного запиту статусу)
405 Method Not Allowed Валідації Метод відправки запиту може бути використаний Запит фінально неуспішний. Операція не створилася на боці платформи (якщо помилка виникла під час створення, не за інших методів)
409 Conflict Валідації Сутність із таким ідентифікатором вже існує. У відповіді повернеться код і повідомлення помилки, в тілі повернуться дані існуючої операції Обробити тіло відповіді з раніше створеною операцією згідно з бізнес-логікою на боці мерчанта
422 Unprocessable Entity Валідації Сервер не може прийняти запит (некоректні дані або налаштування облікового запису) Запит фінально неуспішний. Операція не створилася на боці платформи (якщо помилка виникла під час створення, не за інших методів)

5xx Помилки на боці серверу

Код Опис Інструкції
500 Internal Server Error Внутрішня помилка серверу. Не гарантує помилки створення операції. Необхідно запросити статус операції. У разі відсутності операції на сервері можна повторно викликати метод створення
502 Bad Gateway Проблема обробки запиту. Визначено недійсний шлюз. Не гарантує помилки створення операції. Необхідно запросити статус операції. У разі відсутності операції на сервері можна повторно викликати метод створення
503 Service Unavailable Сервер зараз недоступний. Не гарантує помилку створення операції. Необхідно запросити статус операції. У разі відсутності операції на сервері можна повторно викликати метод створення
504 Gateway Timeout Сервер не зміг повернути відповідь за певний проміжок часу. Не гарантує помилку створення операції. Необхідно запросити статус операції. У разі відсутності операції на сервері можна повторно викликати метод створення

Warning

Якщо створення операції пройшло успішно, а на будь-який інший запит отримано відповідь з 4XX або 5XX HTTP кодом, необхідно уточнювати статус методом реконсиляції або через канали комунікації технічної підтримки.

Note

За використання Callback методу оповіщення, за отримання помилок необхідно дочекатися Callback або викликати метод запиту статусу для уточнення стану операції.