Выплаты¶
Методы и сервисы для выплат¶
Для получения списка доступных методов для проведения операции используются предзапросы.
Предзапрос предусматривает фильтрацию сервисов по инициированной сумме и извлечение из них методов для отображения на странице.
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"
}
}
}
Инициирование выплаты¶
Обратите внимание
Выплаты инициируются только через приватный 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 Corefy/payout-invoices?filter[reference_id]={reference_id}
— для поиска по Ссылочному ID (например, ID заказа)
Method: GET
Пример ответа (JSON) с использованием ID Corefy
{
"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 Corefy/payout-invoices?filter[reference_id]={reference_id}
— для поиска по Ссылочному ID (например, ID заказа)
Method: GET
Пример ответа (JSON) с использованием ID Corefy
{
"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 коды ответов¶
Примеры ответов с кодами и описаниями ошибок
{
"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 или вызвать метод запроса статуса для уточнения состояния операции.