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

​
Collections

Initialize a payment session and get back a single RouteX checkout URL. If you send gateway_code, RouteX will try that gateway first. If you omit it, RouteX routes automatically.

​
Request

FieldRequiredDescription
referenceYesUnique merchant reference for this checkout.
amountYesAmount in customer-facing currency units. For example, send 2500 for NGN 2,500.
currencyYesCurrency code. This MVP supports NGN.
customer.emailYesCustomer email address.
customer.nameNoOptional customer display name.
gateway_codeNoOptional gateway override. Use pstk, fltw, kora, or isw.
redirect_urlNoOptional customer return URL after payment.
notification_urlNoOptional merchant webhook URL for normalized RouteX events.
narrationNoOptional checkout narration.
modeNoOptional checkout channel hint.
metadataNoOptional metadata object.

​
Example request

{
  "reference": "ORD_1001",
  "amount": 2500,
  "currency": "NGN",
  "gateway_code": "isw",
  "customer": {
    "email": "buyer@example.com",
    "name": "Ada Obi"
  },
  "redirect_url": "https://merchant.example.com/return",
  "notification_url": "https://merchant.example.com/webhook",
  "narration": "Invoice payment",
  "mode": "card",
  "metadata": {
    "order_id": "ORD_1001"
  }
}

​
Example response

{
  "status": true,
  "message": "Charge created successfully",
  "reference": "ORD_1001",
  "checkout_url": "https://checkout.routex.xoroai.cloud/ORD_1001/20260325",
  "selected_gateway": "isw",
  "gateway_reference": "ISW_PROC_001",
  "routing": {
    "decision_id": "route_decision_123",
    "selected_gateway": "isw",
    "selection_reason": "highest score among eligible gateways",
    "fallback_order": ["isw", "pstk", "fltw", "kora"],
    "score_breakdown": {
      "isw": 97.2,
      "pstk": 91.5,
      "fltw": 88.1,
      "kora": 83.4
    }
  }
}

​
Notes

  • gateway_code is optional.
  • When gateway_code is omitted, RouteX picks the gateway automatically.
  • RouteX handles gateway-specific amount conversion internally.
  • If you send notification_url, RouteX uses it for merchant webhook delivery after provider confirmation.