> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperrails.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fiat Payout Process

> A comprehensive guide to managing and executing fiat payouts on Hyperrails

# 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:

<Steps>
  <Step title="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](/api-reference/banks/get-all).

    This is currently supported for **NGN** and **GHS**.
  </Step>

  <Step title="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](/api-reference/banks/resolve). This returns the verified account name on record.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Test Mode Behavior

<Info>
  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"**
</Info>

***

## Create Fiat Payout

**Endpoint**
POST [https://api.hyperrails.io/api/v1/partners/payouts](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

<ParamField body="reference" type="string" required>
  A unique reference you generate for this transaction. Used to prevent duplicate payouts. Max 50 characters.
</ParamField>

<ParamField body="amount" type="number" required>
  The amount to pay out from your HyperRail wallet balance.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 3-letter currency code. Example: `NGN`, `GHS`, `USD`.
</ParamField>

<ParamField body="destination" type="object" required>
  The recipient's bank details.

  <Expandable title="destination properties">
    <ParamField body="accountNumber" type="string" required>
      The recipient's bank account number.
    </ParamField>

    <ParamField body="accountName" type="string" required>
      The recipient's account name. Must match the name returned by the Resolve Bank Account API.
    </ParamField>

    <ParamField body="bankCode" type="string" required>
      The recipient's bank code from the Get All Banks API. Example: `SPB-1938`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="narration" type="string">
  Optional description shown to the recipient on their bank statement.
</ParamField>

***

## Code Sample

<CodeGroup>
  ```bash cURL theme={"dark"}
  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"
    }'
  ```
</CodeGroup>

### Response

```json theme={"dark"}
{
  "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](mailto:support@hyperrails.io)