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

# Payout rails API

> List banks, MoMo operators, and resolve account names for withdrawals.

Merchant **payout rails** endpoints live under `/api/v1/merchant/rails/*`. They require [signed requests](/getting-started/authentication).

Use these to build withdrawal forms: bank dropdowns, MoMo operator lists, and account-name preview before saving a payout method.

## Endpoints

| Method | Path                      | Description                                 |
| ------ | ------------------------- | ------------------------------------------- |
| `GET`  | `/rails/meta`             | Business country and fiat rail availability |
| `GET`  | `/rails/banks`            | Bank institutions for merchant country      |
| `GET`  | `/rails/mobile-providers` | MoMo operators for merchant currency        |
| `GET`  | `/rails/resolve`          | Preview account holder name                 |

## Payout rails meta

`GET /api/v1/merchant/rails/meta`

Returns the business country, fiat currency, and whether local fiat rails are available.

<RequestExample>
  ```bash cURL theme={null}
  curl -s "https://api.morapay.io/api/v1/merchant/rails/meta" \
    -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
    -H "Morapay-Timestamp: $TIMESTAMP" \
    -H "Morapay-Signature: v1=$SIGNATURE"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "data": {
      "fiatRailsSupported": true,
      "payoutCurrencyFiat": "GHS",
      "businessCountry": "GH"
    }
  }
  ```
</ResponseExample>

## List banks

`GET /api/v1/merchant/rails/banks`

Returns bank institutions for the merchant's country. Requires `fiatRailsSupported: true` from meta.

<ResponseExample>
  <CodeGroup>
    ```json 200 OK theme={null}
    {
      "success": true,
      "data": {
        "banks": [
          {
            "id": 76,
            "name": "Absa Bank Ghana Ltd",
            "code": "030100",
            "slug": "absa-bank-ghana-ltd",
            "type": "ghipss",
            "currency": "GHS"
          }
        ]
      }
    }
    ```

    ```json 400 Bad Request theme={null}
    {
      "success": false,
      "error": "Fiat payout rails are not available for this business.",
      "code": "request.invalid",
      "requestId": "req_banks400"
    }
    ```
  </CodeGroup>
</ResponseExample>

## List mobile money operators

`GET /api/v1/merchant/rails/mobile-providers`

Returns MoMo operators for the merchant's fiat currency such as GHS, NGN.

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "data": {
      "providers": [
        { "name": "MTN", "code": "MTN", "slug": "mtn-mobile-money" },
        { "name": "Telecel", "code": "VOD", "slug": "vod-mobile-money" }
      ]
    }
  }
  ```
</ResponseExample>

## Resolve account name

`GET /api/v1/merchant/rails/resolve`

Preview the account holder name before creating a payout method.

### Query parameters

| Parameter        | Type   | Required | Description                      |
| ---------------- | ------ | -------- | -------------------------------- |
| `type`           | string | Yes      | `BANK_ACCOUNT` or `MOBILE_MONEY` |
| `bank_code`      | string | Bank     | Bank or provider code            |
| `account_number` | string | Bank     | 6–20 digit account number        |
| `phone`          | string | MoMo     | Mobile number                    |
| `provider_hint`  | string | MoMo     | e.g. `MTN`, `VOD`, `ATL`         |

<RequestExample>
  ```bash cURL theme={null}
  curl -s "https://api.morapay.io/api/v1/merchant/rails/resolve?type=BANK_ACCOUNT&bank_code=030100&account_number=0123456789" \
    -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
    -H "Morapay-Timestamp: $TIMESTAMP" \
    -H "Morapay-Signature: v1=$SIGNATURE"
  ```
</RequestExample>

<ResponseExample>
  <CodeGroup>
    ```json 200 OK theme={null}
    {
      "success": true,
      "data": {
        "accountName": "JOHN DOE"
      }
    }
    ```

    ```json 422 Unprocessable Entity theme={null}
    {
      "success": false,
      "error": "Account name could not be resolved.",
      "code": "payouts.momo.account_not_found",
      "requestId": "req_resolve422"
    }
    ```
  </CodeGroup>
</ResponseExample>

## Public validation for checkout

For payer-facing checkout flows, use the unsigned public validation endpoints:

| Endpoint                                     | Method | Purpose                                        |
| -------------------------------------------- | ------ | ---------------------------------------------- |
| `/api/public/validate/momo`                  | POST   | Validate MoMo number                           |
| `/api/public/validate/bank`                  | POST   | Validate bank account                          |
| `GET /api/public/validate/banks?country=gha` | GET    | Bank list for Ghana (`gha`) or Nigeria (`nga`) |

Example MoMo validate body:

```json theme={null}
{
  "receiver": "233241234567",
  "provider": "MTN",
  "currency": "GHS"
}
```

## Errors

| HTTP    | Typical cause                                   |
| ------- | ----------------------------------------------- |
| **401** | Missing or invalid signed headers               |
| **403** | LIVE action blocked by KYB tier                 |
| **404** | Unknown bank code or unresolved account         |
| **422** | Invalid phone, account number, or provider hint |

<ResponseExample>
  <CodeGroup>
    ```json 401 Unauthorized theme={null}
    {
      "success": false,
      "error": "Invalid API key or signature.",
      "code": "auth.keys.invalid",
      "requestId": "req_rails401"
    }
    ```

    ```json 400 Bad Request theme={null}
    {
      "success": false,
      "error": "Fiat payout rails are not available for this business.",
      "code": "request.invalid",
      "requestId": "req_rails400"
    }
    ```

    ```json 422 Unprocessable Entity theme={null}
    {
      "success": false,
      "error": "Account name could not be resolved.",
      "code": "payouts.momo.account_not_found",
      "requestId": "req_resolve422"
    }
    ```
  </CodeGroup>
</ResponseExample>

## Related

* [Banks & MoMo reference](/reference/banks-and-momo)
* [Disbursement API](/api-reference/disbursement)