Skip to content

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_idthe unique identifier of the operation on the merchant side
  • servicethe service identifier, for example payment_card_usd_hpp: find a full list of available services in the dashboard or through Private API request
  • currencythe invoice currency
  • amountthe invoice amount in the float format, for example: 100.55
  • fieldsdepends on required parameters of the payout service

Additional fields:

  • callback_urlURL to send Callbacks when the transaction status changes: replaces the Callback URL parameter specified for the account in general
  • contextrecipient's additional data (such as Cardholder, Card expiry date)
  • description
  • customer - object contains the client’s basic data and any associated metadata
    • reference_id required attribute for the customer object in the request
    • name
    • email
    • phone
    • individual_tax_id
    • date_of_birth
    • metadata
    • address
      • country
      • region
      • city
      • street
      • full_address
      • post_code
  • optionsprocessing parameters: before using, you should clarify available account options with your Cublox support manager
  • metadata - 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 Cublox ID
  • /payout-invoices?filter[reference_id]={reference_id} — or by Reference ID

Method: GET

Response Sample (JSON) using Cublox 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 Cublox ID
  • /payout-invoices?filter[reference_id]={reference_id} — or by Reference ID

Method: GET

Response Sample (JSON) using Cublox 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