Виплати¶

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

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

Pre-request передбачає фільтрування активних сервісів за валютою, сумою та отримання з них списку унікальних методів.

API: PUBLIC

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

Endpoint: /payout-prerequest

Method: POST

Приклади (JSON)

Запит

{
"currency":"USD",
"amount":10,
"public_key":"pk_test_NM6Rpg6A29zNlSQHiCsprOJyT9WXuFa76WcwwBB69cS"
}

Відповідь

{
    "data":{
        "currency":"USD",
        "amount":10,
        "test_mode":true,
        "services":{
            "test_uah":{
                "code":"test_uah",
                "method":"test",
                "currency":"USD",
                "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_jpy",
                "service_method":"swift",
                "service_currency":"JPY",
                "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":"GBP",
                "test_mode":true
            },
            "relationships":{
                "payout-method":{
                "data":{
                    "type":"payout-methods",
                    "id":"swift"
                }
                },
                "payout-service":{
                "data":{
                    "type":"payout-services",
                    "id":"swift_jpy"
                }
                }
            },
            "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":"USD",
                "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_jpy",
            "service_method": "swift",
            "service_currency": "JPY",
            "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": "GBP",
            "test_mode": true
        },
        "relationships": {
            "payout-method": {
                "data": {
                    "type": "payout-methods",
                    "id": "swift"
                }
            },
            "payout-service": {
                "data": {
                    "type": "payout-services",
                    "id": "swift_jpy"
                }
            }
        },
        "links": {
            "self": "/api/payout-services/comcpos_RHUGUgEnmmedR7h3"
        }
    }
}

Створення виплати¶

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

Виплату можна створити лише використовуючи PRIVATE API.

Створення Інвойса¶

API: PRIVATE

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

Endpoint: /payout-invoices

Method: POST

Обов'язкові атрибути:

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

Додаткові атрибути:

callback_url - Callback URL для отримання серверних повідомлень про зміну статусу інвойса: є пріоритетною альтернативою Callback URL, встановленого в налаштуваннях акаунту
context - додаткові атрибути отримувача.Наприклад: Cardholder або Card expiry date. Деякі провайдери вимагають їх для проведення транзакції. Уточнюйте необхідність у менеджера
description - внутрішній комернтар до транзакції
customer - об'єкт, що містить дані користувача
- reference_id обов'язковий атрибут при наявності о'бєкту в запиті
- name
- email
- phone
- individual_tax_id
- date_of_birth
- metadata
- address - об'єкт що містить додаткові атрибути користувача, пов'язані з адресою
  - country
  - region
  - city
  - street
  - full_address
  - post_code
options - параметри, що впливають на процесування транзакції. За необхідності - уточнюйте набір доступних вам опцій у менеджера
metadata

JSON

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

{
    "data":{
        "type":"payout-invoice",
        "attributes":{
            "service":"card",
            "currency":"USD",
            "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": "USD",
            "service_currency": "USD",
            "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": "USD",
            "service_currency": "USD",
            "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 Back Office
/payout-invoices?filter[reference_id]={reference_id} — для пошуку вашому ID

Method: GET

Приклад відповіді (JSON) з використанням ID Back Office

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

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

API: PRIVATE

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

Endpoint:

/payout-invoices/{id} — для пошуку по ID Back Office
/payout-invoices?filter[reference_id]={reference_id} — для пошуку вашому ID

Method: GET

Приклад відповіді (JSON) з використанням ID Back Office

{
    "data": {
        "type": "payout-invoices",
        "id": "cpoi_VdHYVxq4RsLEebAQ",
        "attributes": {
            "serial_number": "VdHYVxq4RsLEebAQ",
            "status": "processed",
            "resolution": "ok",
            "amount": 10,
            "payout_amount": 10,
            "currency": "USD",
            "service_currency": "USD",
            "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": "USD",
                "service_currency": "USD",
                "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": "USD",
                "service_currency": "USD",
                "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`	Транспортна	Запит некоретної структури, сервер не може його прийняти	Необхідно уточнити статус транзакції
`401 Unauthorized`	Авторизації	Для получения запрашиваемого ответа нужна аутентификация	Первірте авторизаційні параметри. Запит неуспішний. Транзакція не створиться на стороні платформи (якщо ця помилка виникла при створенні. Не розповсюджується на інші запити)
`403 Forbidden`	Авторизациії	Немає доступу до функції, яку викликали	Перевірте авторизаційні дані. Запит неуспішний. Транзакція не створиться на стороні платформи (якщо ця помилка виникла при створенні. Не розповсюджується на інші запити)
`404 Not Found`	Валідації	Сервер не може знайти транзакцію або функцію що викликали	За використання коректної структури запиту статусу означає "транзакцію не знайдено", в такому разі можна повторити інвойс
`405 Method Not Allowed`	Валідації	Метод запиту не дозволений для цієї функції	Запит неуспішний. Транзакція не створиться на стороні платформи (якщо ця помилка виникла при створенні. Не розповсюджується на інші запити)
`409 Conflict`	Валідації	Транзаеція з таким ID вже існує. В тілі відповіді будуть дані інвойса, який є в системі	Не можна сприймати відповідь, як успішне створення транзакції. Необхідно коректно обробити відповідь як "дублікат", у разі необхідності звернутись до команди підтримки
`422 Unprocessable Entity`	Валідації	Запит містить некоректний набір атрибутів або їх значень	Запит неуспішний. Транзакція не створиться на стороні платформи (якщо ця помилка виникла при створенні. Не розповсюджується на інші запити)

5xx Помилки на стороні сервера¶

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

Warning

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

Note

При використанні Callbacks — у разі отримання серверних помилок - дочекайтесь Callback чи: перевірте статус транзакції запитом реконсиляції або зверніться до команди підтримки.