Виплати¶

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

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

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

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 - параметри процесингу виплат. Необхідно уточнювати опції, доступні для облікового запису та логіку їхньої роботи
metadata
- purpose- "F108 39 Повернення коштів, внесених гравцями для участі в азартних іграх казино в мережі Інтернет"
  або
  "F108 45 Виплата виграшів гравцям азартних ігор казино в мережі Інтернет"
  або
  "F108 41 Повернення коштів, внесених гравцями для участі в азартних іграх з букмекерської діяльності в мережі Інтернет"
  або
  "F108 47 Виплата виграшів гравцям азартних ігор з букмекерської діяльності в мережі Інтернет"
- tax- сума сплаченого податку
Примітка для учасників МСС 7995

Мерчант з 1 ліцензією: у разі відсутності поля "purpose" в "metadata", не передані параметри відповідно типу транзакції (повернення коштів або виплата виграшів) та роду діяльності, автоматично буде фіксуватися код та призначення: "F108 (код діяльності) Виплата виграшів гравцям азартних ігор (деталізація роду діяльності) в мережі Інтернет"
Мерчант з 2 та більше ліцензіями: у разі відсутності поля "purpose" в "metadata", не передані параметри відповідно типу транзакції (повернення коштів або виплата виграшів) та роду діяльності, автоматично буде фіксуватися код та призначення: "F108 (код діяльності) Виплата виграшів гравцям азартних ігор (деталізація роду діяльності) в мережі Інтернет" відповідно до першої ОТРИМАНОЇ ліцензії при співпраці
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":{
                "purpose":"Повернення коштів, внесених гравцями для участі в азартних іграх",
                "tax":"0"
            }
        }
    }
}

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

{
    "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": {
                "purpose": "Повернення коштів, внесених гравцями для участі в азартних іграx ",
                "tax": "0"
            },
            "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 коди відповідей¶

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

401 (unauthorized)

{
    "errors": [
        {
            "status": "Unauthorized",
            "code": "401"
        }
    ]
}

404 (not found)

{
    "errors": [
        {
            "status": "Not Found",
            "code": "404"
        }
    ]
}

405 (incorrect method)

{
    "errors": [
        {
            "status": "Method Not Allowed",
            "code": "405"
        }
    ]
}

422 (validation error)

{
    "errors": {
        "amount": "This value should be greater than 0."
    }
}

500 (internal server error)

{
    "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 або викликати метод запиту статусу для уточнення стану операції.