Skip to main content
POST
/
api
/
v1
/
payout
Payouts
curl --request POST \
  --url https://routexapi.xoroai.cloud/api/v1/payout \
  --header 'Authorization: Bearer <token>'

​
Payouts

Create a payout request with one RouteX endpoint and let RouteX pick an eligible payout path.

​
Request

FieldRequiredDescription
referenceYesUnique merchant payout reference.
amountYesAmount to pay out in customer-facing units.
currencyYesCurrency code such as NGN.
customer.emailYesRecipient email address.
customer.nameNoRecipient name if you have it.
destination.bank_codeYesBank code for the destination account.
destination.account_numberYesDestination account number.
metadataNoOptional payout metadata.
narrationNoOptional payout narration.

​
Example request

{
  "reference": "PAYOUT_1001",
  "amount": 5000,
  "currency": "NGN",
  "customer": {
    "email": "recipient@example.com",
    "name": "Grace"
  },
  "destination": {
    "bank_code": "044",
    "account_number": "0123456789"
  },
  "metadata": {
    "batch": "march-settlement"
  },
  "narration": "Vendor settlement"
}

​
Example response

{
  "status": true,
  "message": "Payout processed successfully",
  "reference": "PAYOUT_1001",
  "selected_gateway": "kora",
  "gateway_reference": "KORA_PROC_001",
  "routing": {
    "decision_id": "route_decision_456",
    "selected_gateway": "kora",
    "selection_reason": "best payout availability",
    "fallback_order": ["kora", "pstk"],
    "score_breakdown": {
      "kora": 95.7,
      "pstk": 88.3
    }
  },
  "data": {
    "amount": 5000,
    "fee": 50,
    "reference": "PAYOUT_1001",
    "customer": {
      "email": "recipient@example.com",
      "name": "Grace"
    }
  }
}

​
Notes

  • Payouts use the same merchant auth flow as collections.
  • RouteX keeps the merchant-facing reference and gateway reference separate.
  • If a payout webhook is configured, RouteX delivers normalized events to your notification_url.