Skip to main content
POST
/
api
/
v1
/
payout
Payout
curl --request POST \
  --url https://routexapi.xoroai.cloud/api/v1/payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 5000,
  "currency": "NGN",
  "reference": "PAYOUT_123456",
  "customer": {
    "email": "jsmith@example.com",
    "name": "<string>"
  },
  "destination": {
    "bank_code": "044",
    "account_number": "0123456789"
  }
}
'
{ "status": true, "message": "Payout processed successfully", "data": { "amount": 5000, "customer": { "email": "customer@example.com", "name": "John Doe" }, "fee": 50, "reference": "PAYOUT_123456" }, "reference": "PAYOUT_123456", "selected_gateway": "kora", "gateway_reference": "KORA_PROC_001", "routing": { "decision_id": "<string>", "selection_reason": "highest score among eligible gateways", "fallback_order": [ "<string>" ], "score_breakdown": {} } }

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
amount
number
required

Amount to payout

Example:

5000

​
currency
string
required

Currency code in ISO format

Example:

"NGN"

​
reference
string
required

Unique payout reference

Example:

"PAYOUT_123456"

​
customer
Customer · object
required

Customer details

​
destination
Destination · object
required

Destination bank details

​
metadata
Metadata · object

Custom metadata for the payout

Example:
{ "order_id": "123" }
​
narration
string | null

Optional narration for the payout

Example:

"Payment for order 123"

Response

Successful Response

​
status
boolean
required

Indicates if the payout was successful

Example:

true

​
message
string
required

Human-readable message

Example:

"Payout processed successfully"

​
data
Data · object
required

Details of the payout including fees and customer information

Example:
{
  "amount": 5000,
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "fee": 50,
  "reference": "PAYOUT_123456"
}
​
reference
string | null

Merchant-facing payout reference

Example:

"PAYOUT_123456"

​
selected_gateway
string | null

Gateway selected by the router

Example:

"kora"

​
gateway_reference
string | null

Gateway-facing reference for the routed payout

Example:

"KORA_PROC_001"

​
routing
RoutingMetadata · object

Routing decision details for the payout