Выплаты¶

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

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

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

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 MilkyPay
/payout-invoices?filter[reference_id]={reference_id} — для поиска по Ссылочному ID (например, ID заказа)

Method: GET

Пример ответа (JSON) с использованием ID MilkyPay

{
    "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 MilkyPay
/payout-invoices?filter[reference_id]={reference_id} — для поиска по Ссылочному ID (например, ID заказа)

Method: GET

Пример ответа (JSON) с использованием ID MilkyPay

{
    "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`	Транспортная	Запрос невалидной структуры, сервер не может его обработать	Необходимо запросить статус операции (если использован правильный метод, но на запрос статуса получена 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 или вызвать метод запроса статуса для уточнения состояния операции.