Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hyperrail.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Fiat Payout Process

A fiat payout allows partners to securely disburse funds from their wallet balances directly into standard bank accounts. To ensure higher success rates, minimize failed routing, and prevent fraudulent transfers, Hyperrails orchestrates fiat payouts via a strict three-step lifecycle.

​
The 3-Step Payout Lifecycle

Before submitting a payout request, your backend must follow this sequential process:
1

Retrieve the Bank Code

Different regions and financial systems use different clearing identifiers. Before executing a transfer, fetch the bank code for the target currency using the Get All Banks API.This is currently supported for NGN and GHS.
2

Verify the Recipient's Account Name

To confirm funds are going to the right person, pass the account number and the bankCode from Step 1 to the Resolve Bank Account API. This returns the verified account name on record.
3

Initiate the Fiat Payout

Once you have the bank code, account number, and verified account name, pass them as a single payload to the Payout endpoint to debit your wallet and route the transfer to the clearing network.

​
Test Mode Behavior

When using test API keys (sk_test_...), payouts bypass live banking networks.
  • Any value works for bankCode and accountNumber
  • All accounts automatically resolve to “John Doe”

​
Create Fiat Payout

Endpoint POST https://api.hyperrails.io/api/v1/partners/payouts

​
Headers

HeaderValueRequired
AuthorizationBearer sk_live_... or Bearer sk_test_...Yes
Content-Typeapplication/jsonYes

​
Request Body

​
reference
string
required
A unique reference you generate for this transaction. Used to prevent duplicate payouts. Max 50 characters.
​
amount
number
required
The amount to pay out from your HyperRail wallet balance.
​
currency
string
required
ISO 3-letter currency code. Example: NGN, GHS, USD.
​
destination
object
required
The recipient’s bank details.
​
narration
string
Optional description shown to the recipient on their bank statement.

​
Code Sample

curl --request POST \
  --url https://api.hyperrails.io/api/v1/partners/payouts \
  --header 'Authorization: Bearer sk_test_3c7xxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "reference": "ref-092039",
    "amount": 200,
    "currency": "NGN",
    "destination": {
      "accountNumber": "9829832929",
      "accountName": "John Doe",
      "bankCode": "SPB-1938"
    },
    "narration": "test transfer"
  }'

​
Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "reference": "ref-092039",
    "amount": 200.00,
    "currency": "NGN",
    "status": "PENDING",
    "fee": 10.00,
    "destination": {
      "accountNumber": "9829832929",
      "accountName": "John Doe",
      "bankCode": "SPB-1938"
    },
    "createdAt": "2026-05-19T16:04:21.000Z"
  }
}

​
Need Help?

Contact the HyperRail support team at support@hyperrails.io