RouteX
Start Testing
API Reference

RouteX API reference for collections, payouts, and verification.

Use the core RouteX merchant endpoints with clean payload examples, response bodies, and test-mode request samples.

Base URLhttps://routexapi.xoroai.cloudTest mode

Collections

Confirm the normalized outcome of a customer payment from one endpoint, regardless of the underlying PSP.

POSTMerchant key required

Initialize a routed collection

/api/v1/initiate

Initiate Checkout

Request body

11 fields
FieldTypeRequiredDescriptionExample
customerCustomerYesNo description provided.{"email":"buyer@example.com","name":"string"}
customer.emailstring (email)YesNo description provided.buyer@example.com
customer.namestringNoNo description provided.string
amountnumberYesNo description provided.25000
currencyNGN | KES | GES | XAF | XOF | EGP | TZS | BTC | ETH | USDT | SOLYesCurrency in lower caseNGN
referencestringYesNo description provided.ORD_1001
redirect_urlstringNoNo description provided.https://merchant.example.com/callback
notification_urlstringNoNo description provided.https://merchant.example.com/callback
narrationstringNoNo description provided.string
modecard | bank_transfer | crypto | mobile_moneyNoNo description provided.card
metadataobjectNoNo description provided.{}

Request payload

JSON
{
  "customer": {
    "email": "buyer@example.com",
    "name": "string"
  },
  "amount": 25000,
  "currency": "NGN",
  "reference": "ORD_1001",
  "redirect_url": "https://merchant.example.com/callback",
  "notification_url": "https://merchant.example.com/callback",
  "narration": "string",
  "mode": "card",
  "metadata": {}
}

cURL

Ready to copy
curl --request POST \
  --url "https://routexapi.xoroai.cloud/api/v1/initiate" \
  --header "Authorization: Bearer ROUTEX_TEST_xxx" \
  --header "Content-Type: application/json" \
  --data '{
  "customer": {
    "email": "buyer@example.com",
    "name": "string"
  },
  "amount": 25000,
  "currency": "NGN",
  "reference": "ORD_1001",
  "redirect_url": "https://merchant.example.com/callback",
  "notification_url": "https://merchant.example.com/callback",
  "narration": "string",
  "mode": "card",
  "metadata": {}
}'

Responses

5 variants
HTTP 200HTTP 200

Successful Response

{
  "status": true,
  "message": "Charge created successfully",
  "reference": "ORD_1001",
  "checkout_url": "https://merchant.example.com/callback",
  "selected_gateway": "string",
  "gateway_reference": "ORD_1001",
  "routing": {
    "decision_id": "string",
    "selection_reason": "highest score among eligible gateways",
    "fallback_order": [
      "string"
    ],
    "score_breakdown": {}
  }
}
HTTP 400Duplicate reference

Bad request, e.g., duplicate transaction reference

{
  "detail": "Transaction reference not unique for merchant"
}
HTTP 403Invalid token

Invalid payment secret key

{
  "detail": "Invalid payment secret key provided"
}
HTTP 404Merchant not found

Merchant not found

{
  "detail": "Merchant not found"
}
HTTP 422HTTP 422

Validation Error

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GETMerchant key required

Verify a transaction

/api/v1/transactions/verify

Verify

Query parameters

1 fields
FieldTypeRequiredDescriptionExample
referencestringYesTransaction referenceORD_1001

cURL

Ready to copy
curl --request GET \
  --url "https://routexapi.xoroai.cloud/api/v1/transactions/verify?reference=ORD_1001" \
  --header "Authorization: Bearer ROUTEX_TEST_xxx" \

Responses

5 variants
HTTP 200HTTP 200

Successful Response

{
  "status": true,
  "message": "Verification successful",
  "data": {
    "reference": "TXN_123456",
    "status": "success",
    "domain": "TEST",
    "type": "PAYMENT",
    "amount": 5000,
    "fee": 50,
    "currency": "NGN",
    "narration": "string",
    "metadata": {},
    "created_at": "2025-09-17T12:00:00Z",
    "updated_at": "2025-09-17T12:05:00Z",
    "selected_gateway": "string",
    "gateway_reference": "ORD_1001",
    "attempts": [
      {
        "attempt_no": 1,
        "gateway": "string",
        "status": "string",
        "gateway_reference": "ORD_1001",
        "latency_ms": 1
      }
    ],
    "customer": {
      "email": "buyer@example.com",
      "name": "string"
    }
  }
}
HTTP 400Invalid reference format

Bad request or verification failed

{
  "detail": "Verification failed: invalid reference format"
}
HTTP 403Invalid token

Invalid payment secret key

{
  "detail": "Invalid payment secret key provided"
}
HTTP 404Merchant not found

Merchant or transaction not found

{
  "detail": "Merchant not found"
}
HTTP 422HTTP 422

Validation Error

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GETNone

GET /public/openapi.json

/public/openapi.json

Public Openapi

cURL

Ready to copy
curl --request GET \
  --url "https://routexapi.xoroai.cloud/public/openapi.json" \

Responses

1 variants
HTTP 200HTTP 200

Successful Response

"string"

Payouts

Disburse funds through the unified payout surface while keeping routing, fees, and gateway references consistent.

POSTMerchant key required

Create a payout

/api/v1/payout

Payout

Request body

11 fields
FieldTypeRequiredDescriptionExample
amountnumberYesAmount to payout5000
currencystringYesCurrency code in ISO formatNGN
referencestringYesUnique payout referencePAYOUT_123456
customerCustomerYesCustomer details{"email":"buyer@example.com","name":"string"}
customer.emailstring (email)YesNo description provided.buyer@example.com
customer.namestringNoNo description provided.string
destinationDestinationYesDestination bank details{"bank_code":"044","account_number":"0123456789"}
destination.bank_codestringYesBank code of the destination bank044
destination.account_numberstringYesDestination bank account number0123456789
metadataobjectNoCustom metadata for the payout{}
narrationstringNoOptional narration for the payoutstring

Request payload

JSON
{
  "amount": 5000,
  "currency": "NGN",
  "reference": "PAYOUT_123456",
  "customer": {
    "email": "buyer@example.com",
    "name": "string"
  },
  "destination": {
    "bank_code": "044",
    "account_number": "0123456789"
  },
  "metadata": {},
  "narration": "string"
}

cURL

Ready to copy
curl --request POST \
  --url "https://routexapi.xoroai.cloud/api/v1/payout" \
  --header "Authorization: Bearer ROUTEX_TEST_xxx" \
  --header "Content-Type: application/json" \
  --data '{
  "amount": 5000,
  "currency": "NGN",
  "reference": "PAYOUT_123456",
  "customer": {
    "email": "buyer@example.com",
    "name": "string"
  },
  "destination": {
    "bank_code": "044",
    "account_number": "0123456789"
  },
  "metadata": {},
  "narration": "string"
}'

Responses

6 variants
HTTP 200HTTP 200

Successful Response

{
  "status": true,
  "message": "Payout processed successfully",
  "reference": "ORD_1001",
  "selected_gateway": "string",
  "gateway_reference": "ORD_1001",
  "routing": {
    "decision_id": "string",
    "selection_reason": "highest score among eligible gateways",
    "fallback_order": [
      "string"
    ],
    "score_breakdown": {}
  },
  "data": {
    "amount": 5000,
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "fee": 50,
    "reference": "PAYOUT_123456"
  }
}
HTTP 400Insufficient balance

Bad request, e.g., insufficient balance or duplicate reference

{
  "detail": "Insufficient balance"
}
HTTP 403Invalid token

Invalid token or bank code

{
  "detail": "Invalid payment secret key"
}
HTTP 404Merchant not found

Merchant not found

{
  "detail": "Merchant not found"
}
HTTP 409Invalid account conflict

Conflict - invalid account

{
  "status": false,
  "message": "Invalid account.",
  "data": {
    "amount": 5000,
    "fee": 50,
    "reference": "PAYOUT_12346",
    "customer": {
      "email": "user@example.com",
      "name": "string"
    }
  }
}
HTTP 422Amount less than minimum

Invalid request, e.g., amount less than minimum 200

{
  "detail": "Amount must be greater than 200"
}