Make Payouts by Reference Details¶
Payout Methods and Services¶
Use pre-requests to obtain the list of services available for any particular currency.
The payout pre-request filter and show services by the invoice amount.
API: PUBLIC
Authentication: live or test Public keys
Endpoint: /payout-prerequest
Method: POST
Samples (JSON)
{
"currency":"USD",
"amount":10,
"public_key":"pk_live_NM6Rpg6A29zNlSQHiCsprOJyT9WXuFa76WcwwBB69cS"
}
{
"data":{
"currency":"USD",
"amount":10,
"test_mode":true,
"services":{
"test_usd":{
"code":"test_usd",
"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"
}
}
}
}
Obtain the List of Available Services via Private API¶
Full List of Payout Services¶
API: PRIVATE
Endpoint: /payout-services
Authentication: BasicAuth
Method: GET
Request Sample (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"
}
}
}
}
]
}
Payout Service by ID¶
API: PRIVATE
Endpoint: /payout-services/{id} where id is taken from the previous request
Authentication: BasicAuth
Method: GET
Response Sample (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"
}
}
}
Invoice Initiation¶
API: PRIVATE
Endpoint: /payout-invoices
Authentication: BasicAuth
Method: POST
Required fields:
reference_id— the unique identifier of the operation on the merchant sideservice— the service identifier, for examplepayment_card_usd_hpp: find a full list of available services in the dashboard or through Private API requestcurrency— the invoice currencyamount— the invoice amount in the float format, for example:100.55fields— depends on required parameters of the payout service
Additional fields:
callback_url— URL to send Callbacks when the transaction status changes: replaces the Callback URL parameter specified for the account in generalcontext— recipient's additional data (such as Cardholder, Card expiry date)descriptioncustomer- object contains the client’s basic data and any associated metadatareference_idrequired attribute for thecustomerobject in the requestnameemailphoneindividual_tax_iddate_of_birthmetadataaddresscountryregioncitystreetfull_addresspost_code
options— processing parameters: before using, you should clarify available account options with your MilkyPay support managermetadata- for the Invoice
JSON
{
"data":{
"type":"payout-invoice",
"attributes":{
"service":"card",
"currency":"USD",
"amount":10,
"reference_id":"a5c22bfb-04c1-4dbf-8b46-9753bf1f6570",
"test_mode":true,
"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": null,
"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"
}
}
}
Invoice processing¶
API: PRIVATE
Endpoint: /payout-invoices/{id}/process
Authentication: BasicAuth
Method: POST
Response Sample (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": null,
"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"
}
}
}
Invoice reconciliation by ID¶
Note
Read about invoice statuses in the Guides. Read below about the HTTP status codes used in the API responses.
Via Public API¶
You can't initiate and process a payout via the Public API but can obtain transaction's details.
API: PUBLIC
Authentication: live or test Public keys
Endpoint:
/payout-invoices/{id}— to find the payout by MilkyPay ID/payout-invoices?filter[reference_id]={reference_id}— or by Reference ID
Method: GET
Response Sample (JSON) using MilkyPay ID
{
"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
}
}
Via Private API¶
API: PRIVATE
Authentication: BasicAuth
Endpoint:
/payout-invoices/{id}— to find the payout by MilkyPay ID/payout-invoices?filter[reference_id]={reference_id}— or by Reference ID
Method: GET
Response Sample (JSON) using MilkyPay ID
{
"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": null,
"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"
}
}
}
Get the Full List of Payout Invoices¶
API: PRIVATE
Authentication: BasicAuth
Endpoint: /payout-invoices
Method: GET
Response Sample (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": null,
"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": null,
"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 status codes used in responses¶
Response examples of error codes and descriptions
{
"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 Successful responses¶
| Code | Description |
|---|---|
200 OK | The request has succeeded, the resource has been fetched |
201 Created | The POST request has succeeded and a new resource has been created as a result |
4xx Client error responses¶
| Code | Description | Directives |
|---|---|---|
400 Bad Request | The server could not understand the request due to invalid syntax | Request the transaction status (if the correct method is used, but the status request has received an error 404, you can consider the request unsuccessful and repeat the operation) |
401 Unauthorized | The client must authenticate itself to get the requested response | Check the authorization data. The request is unsuccessful. The operation was not created on the platform side (if the error occurred during creation, not with other methods). |
403 Forbidden | The client does not have access rights to the content. Unlike 401, the client's identity is known to the server | Check the authorization data. The request is unsuccessful. The operation was not created on the platform side (if the error occurred during creation, not with other methods) |
404 Not Found | The endpoint is valid, but the resource itself does not exist | Check the request data: the query specified incorrect method or the transaction does not exist (if the status request is valid) |
405 Method Not Allowed | The request method is known by the server but has been disabled and cannot be used | The request is unsuccessful. The operation was not created on the platform side (if the error occurred during creation, not with the other methods) |
409 Conflict | This response is sent when a request conflicts with the current state of the server: an API returns an error message and duplicate request bod | Process the response body with the previously created transaction according to the merchant's business logic |
422 Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors | The request is unsuccessful. The operation was not created on the platform side (if the error occurred during creation, not with the other methods) |
5xx Server error responses¶
| Code | Description | Directives |
|---|---|---|
500 Internal Server Error | The server has encountered a situation that doesn't know how to handle | Check the transaction status. If there is no transaction with this ID on the server, you can request the creation method again |
502 Bad Gateway | The server got an invalid response while tried to get a response needed to handle the request | Check the transaction status. If there is no transaction with this ID on the server, you can request the creation method again |
503 Service Unavailable | The server is not ready to handle the request (common cause is the server is down for maintenance or overloaded) | Check the transaction status. If there is no transaction with this ID on the server, you can request the creation method again |
504 Gateway Timeout | The server cannot get a response in time | Check the transaction status. If there is no transaction with this ID on the server, you can request the creation method again |