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:

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.

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.

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

Header	Value	Required
`Authorization`	`Bearer sk_live_...` or `Bearer sk_test_...`	Yes
`Content-Type`	`application/json`	Yes

Request Body

string

required

A unique reference you generate for this transaction. Used to prevent duplicate payouts. Max 50 characters.

number

required

The amount to pay out from your HyperRails wallet balance.

string

required

ISO 3-letter currency code. Example: NGN, GHS, USD.

object

required

The recipient’s bank details.

Show destination properties

string

required

The recipient’s bank account number.

string

required

The recipient’s account name. Must match the name returned by the Resolve Bank Account API.

string

required

The recipient’s bank code from the Get All Banks API. Example: SPB-1938.

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 HyperRails support team at support@hyperrails.io

Core Concepts

Supported Currencies

Testing

Features

Webhooks

Expert Desk

Fiat Payout Process

Fiat Payout Process

The 3-Step Payout Lifecycle

Test Mode Behavior

Create Fiat Payout

Headers

Request Body

Code Sample

Response

Need Help?

​Fiat Payout Process

​The 3-Step Payout Lifecycle

​Test Mode Behavior

​Create Fiat Payout

​Headers

​Request Body

​Code Sample

​Response

​Need Help?

Fiat Payout Process

The 3-Step Payout Lifecycle

Test Mode Behavior

Create Fiat Payout

Headers

Request Body

Code Sample

Response

Need Help?