Payouts
Payouts offer a way of paying out money to a consumer, directly to their bank account. It provides a standard API interface for issuing payouts across various payment processors and banks.
Setup
In order to use payouts, a payment-profile needs to be setup with payment-processor and rail details for each bank
Currently supported payment processors and rails
Payments Way
ach
Mono
ach
turbo
transfiya
Rails
The rails object contains two important objects whose structure may depend on the specific rail:
config
credentials
(all data in this field will be encrypted)
The name
field must correspond to a supported rail name
Mono
Mono provides it's own fallback processing, and the alternative rails are specified in the config.fallback_routing
field.
Request
curl -X POST --location 'https://api.orangepill.cloud/v1/rails' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "turbo",
"config": {
"account_id": "my_acc_number",
"fallback_routing": ["ach"]
},
"credentials": {
"authorization": "Bearer key_012345XY",
"base_url": "https://api.sandbox.cuentamono.com/v1"
},
"active": true,
"deleted": false,
"default": true
}'
Response
{
"id": "67ea61d6b5bb3aea747961ac",
"name": "turbo",
"config": {
"account_id": "my_acc_number",
"fallback_routing": ["ach"]
},
"credentials": {
"authorization": "Bearer key_012345XY",
"base_url": "https://api.sandbox.cuentamono.com/v1"
},
"default": true,
"active": true,
"deleted": false
}
Payments Way
Request
curl -X POST --location 'https://api.orangepill.cloud/v1/rails' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "ach",
"config": {
bank_code": "1007",
},
"credentials": {
"base_url": "http://190.60.126.210:3001/CashOutService.svc",
"username": "MY_USER_NAME",
"password": "my_password
},
"active": true,
"deleted": false,
"default": false
}'
Payment processors
The payment processor name
must correspond to a supported payment processor. The rails
array contains the ids of rails linked to this payment processor.
Request
curl -X POST --location 'https://api.orangepill.cloud/v1/payment-processors' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "mono",
"rails": ["67ea61d6b5bb3aea747961ac"],
"default": true,
"active": true,
"deleted": false
}'
Response
{
"id": "67ea6bc8b5bb3aea747961ad",
"name": "mono",
"default": true,
"active": true,
"deleted": false,
"rails": [
{
"id": "67ea61d6b5bb3aea747961ac",
"name": "turbo",
"config": {
"account_id": "my_acc_number",
"fallback_routing": ["ach"]
},
"credentials": {
"authorization": "Bearer key_012345XY",
"base_url": "https://api.sandbox.cuentamono.com/v1"
},
"default": true,
"active": true,
"deleted": false
}
]
}
Payment profiles
Payment profiles are the top level payout setup category and can contain several payment_processors
The field failover
specifies the fail-over logic in case of a payout transaction failure, and it can contain one of these values:
RAIL - the next transaction will be tried with the same rail of a different payment processor
PAYMENT_PROCESSOR - next transaction will be tried with the next rail of the same payment processor
note: since Mono has it's own fail-over mechanism, this field can be set to null
Request
curl -X POST --location 'https://api.orangepill.cloud/v1/payment-profiles' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "MY_PROFILE",
"payment_processors": ["67ea6bc8b5bb3aea747961ad"],
"failover": "RAIL",
"default": true,
"active": true,
"deleted": false
}'
Response
{
"id": "67ea6f7ab5bb3aea747961ae",
"name": "MY_PROFILE",
"failover": null,
"default": "RAIL",
"active": true,
"deleted": false,
"payment_processors": [
{
"id": "67ea6bc8b5bb3aea747961ad",
"name": "mono",
"default": true,
"active": true,
"deleted": false,
"rails": [
{
"id": "67ea61d6b5bb3aea747961ac",
"name": "turbo",
"config": {
"account_id": "my_acc_number",
"fallback_routing": ["ach"]
},
"credentials": {
"authorization": "Bearer key_012345XY",
"base_url": "https://api.sandbox.cuentamono.com/v1"
},
"default": true,
"active": true,
"deleted": false
}
]
}
]
}
]
Payout
The payout API has a common interface for all payment processors and rails. The payout will be sent using the payment profile specified in the payment_profile
field. If this field is not specified, the payout will be sent with the default payment profile (which will use the default payment processor with the default rail).
Request
curl -X POST --location 'https://api.orangepill.cloud/v1/payout' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"country": "CO",
"payment_profile": "67ea6f7ab5bb3aea747961ae",
"account": "1234567",
"bank": "051",
"account_type": "savings_account",
"amount": 50000,
"notify_url": "http://my-server.com/webhook",
"document": "8881235000",
"document_type": "CC",
"name": "orangepill user",
"email":"[email protected]",
"phone": "+573201111501",
"receiver_id": "122222",
"source_currency": "COP"
}'
Response
{
"id": "67ea7c7eb5bb3aea747961af",
"payment_profile": "67ea6f7ab5bb3aea747961ae",
"payment_processor": "mono",
"rail": "ach",
"bank": "051",
"account": "1234567",
"account_type": "savings_account",
"amount": "50000",
"source_currency": "COP",
"notify_url": "http://my-server.com/webhook",
"country": "CO",
"document": "8881235000",
"document_type": "CC",
"external_id": "trn_02zVPwC62K0NoHV99Uyr3B",
"status": "INIT",
"status_description":""
"name": "orangepill user",
"email":"[email protected]",
"phone": "+573201111501",
"receiver_id": "122222",
"created_at": 1743420542246,
"updated_at": 1743420543365,
"retries": []
}
The initial response represents the data structure of the sent payout.
Subsequent data will be sent to the web hook specified in the notify_url
field with the updated statuses
Status list
INIT - payout initialized and sent to the payment processor
PROCESSING - payout is being processed
COMPLETED - payout transaction successfully completed
FAILED - payout transaction failed
Additional information regarding failed statuses can be found in the status_description
field
Last updated
Was this helpful?