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

# Payouts

> Send money out to any Nigerian bank account

Withdraw funds directly from your wallet to any Nigerian bank account.

<Note>
  Payouts are enabled per-merchant. If it isn't enabled on your account, these endpoints return `403` with `"error_code": "PAYOUT_DISABLED"` — contact support to request access. Limits (min, max per transaction, hourly, daily) are also configured per account; check yours in the merchant dashboard.
</Note>

<Warning>
  Payouts move real money out, so on top of the usual per-minute rate limit, this endpoint caps you at **20 attempts per hour per IP** and a configurable number of attempts per hour per account (`RATE_LIMITED` / `IP_RATE_LIMITED` if you exceed either — both responses include `retry_after` in seconds).
</Warning>

## Get Bank List

**GET** `/api/v1/payout/banks`

Returns supported banks for payout.

```json Response theme={null}
{
    "success": true,
    "data": [
        { "bank_code": "000001", "bank_name": "ACCESS BANK" }
    ]
}
```

***

## Verify Bank Account

**POST** `/api/v1/payout/verify-account`

Resolves an account number to the account holder's name before you send a transfer — always verify before calling Process Payout.

<ParamField body="bank_code" type="string" required>
  Bank code from [Get Bank List](#get-bank-list).
</ParamField>

<ParamField body="account_number" type="string" required>
  10-digit NUBAN account number.
</ParamField>

```json Response theme={null}
{
    "success": true,
    "data": {
        "account_number": "0123456789",
        "account_name": "JOHN DOE",
        "bank_code": "000001"
    }
}
```

***

## Process Payout / Transfer

**POST** `/api/v1/payout/transfer`

<ParamField body="amount" type="number" required>
  Amount to withdraw in Naira (subject to your account's minimum).
</ParamField>

<ParamField body="bank_code" type="string" required>
  Bank code from [Get Bank List](#get-bank-list).
</ParamField>

<ParamField body="account_number" type="string" required>
  10-digit NUBAN account number.
</ParamField>

<ParamField body="account_name" type="string" required>
  Account holder name — use the value [Verify Bank Account](#verify-bank-account) returned.
</ParamField>

<ParamField body="bank_name" type="string" required>
  e.g. `"Access Bank"`.
</ParamField>

<ParamField body="reference" type="string">
  A unique value you choose. Auto-generated if omitted. Must be unique across all your payouts.
</ParamField>

<ParamField body="narration" type="string">
  Transaction narration/description.
</ParamField>

```bash theme={null}
curl -X POST "https://www.abcmpay.com/api/v1/payout/transfer" \
  -H "X-Api-Key: your-public-key" \
  -H "X-Api-Secret: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "bank_code": "000001",
    "account_number": "0123456789",
    "account_name": "JOHN DOE",
    "bank_name": "Access Bank",
    "reference": "PAYOUT_20260215120000"
}'
```

```json Response (201) theme={null}
{
    "success": true,
    "data": {
        "reference": "PAYOUT_20260215120000",
        "amount": 5000,
        "fee": 50,
        "total_deducted": 5050,
        "net_amount": 5000,
        "order_no": "MI2053495351264129024",
        "status": "processing",
        "account": "****6789",
        "created_at": "2026-02-15T12:00:00Z"
    }
}
```

<Info>
  Your wallet is charged `total_deducted` (amount + fee) immediately, before the transfer settles — the fee is 1%, capped at ₦1,000. A payout at or above your account's admin-review threshold comes back with `"status": "pending_approval"` instead: your wallet is still debited (reserved), but the transfer is held until an admin approves it. Your webhook or the status endpoint below tells you when it actually completes.
</Info>

### Status values

| Status             | Meaning                                                       |
| ------------------ | ------------------------------------------------------------- |
| `pending`          | Just created, not yet sent                                    |
| `pending_approval` | Held for admin review (large amount) — wallet already debited |
| `processing`       | Sent to the bank, awaiting confirmation                       |
| `completed`        | Funds delivered                                               |
| `failed`           | Transfer failed — funds are returned to your wallet           |

***

## Check Payout Status

**GET** `/api/v1/payout/status?reference={reference}`

```json Response theme={null}
{
    "success": true,
    "data": {
        "reference": "PAYOUT_20260215120000",
        "amount": 5000,
        "fee": 50,
        "total_deducted": 5050,
        "net_amount": 5000,
        "order_no": "MI2053495351264129024",
        "status": "completed",
        "account": "****6789",
        "created_at": "2026-02-15T12:00:00Z",
        "processed_at": "2026-02-15T12:00:04Z",
        "source": "api",
        "error": null
    }
}
```