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

# Send a bank payout

> Send money from your balance to a bank account.

## What to send

| Field | Required | What it is |
| - | - | - |
| `amount` | Yes | How much to send, in GMD. At least 10. |
| `currency` | Yes | `GMD`. |
| `network` | Yes | The payout channel `code`, like `2007` for Ecobank Gambia. Load the list from [Payout channels](https://docs.modempay.com/documentation/payouts/payout-channels.md) instead of hard-coding it. |
| `account_number` | Yes | The bank account number, at least 7 digits. |
| `beneficiary_name` | Yes | The account holder's name, at least 3 characters. |
| `narration` | No | A note for your records. |
| `metadata` | No | Your own data, like an invoice ID. |
| `callback_url` | No | An HTTPS URL to receive this payout's result. |

You also send an `Idempotency-Key` header: a unique value, like a UUID, for each payout. If you send the same request again with the same key, for example after a timeout, we return the first payout instead of paying twice.

> [!TIP]
>
> Not sure what it will cost? [Check the fee](https://docs.modempay.com/documentation/payouts/fees.md)
> first. The fee is taken from your balance on top of the amount.

## Picking a bank

`network` is the `code` of a payout channel. The list of channels changes over time, so **load it from the API** and let your users pick from it. Don't hard-code channel codes in your app.

```bash cURL theme={null}
curl "https://api.modempay.com/v1/transfers/payout-channels?type=bank" \
  -H "Authorization: Bearer sk_test_..."
```

Here is a recent snapshot of the bank channels. This is a **sample only**, always use the codes the API returns.

| code | name | country |
| - | - | - |
| `2007` | Ecobank Gambia | `gm` |
| `2006` | Trust Bank Ltd | `gm` |
| `2005` | GT Bank | `gm` |
| `2004` | Zenith Bank | `gm` |

Codes never change, so it's safe to store one after a user picks it. If a channel is later switched off, sending a payout to its code returns a `400` saying the channel is currently unavailable, and no money moves.

> [!WARNING]
>
> Bank channels may appear in the payout channels list before bank payouts are
> fully open. Check that the channel's `code` is in the list before letting
> users send to it.

## Look up the account first (recommended)

Before you send a bank payout, confirm the account number belongs to the name you have. This catches typos and mismatches before money moves.

`GET /v1/transfers/account-lookup/:network/:account_number`

```bash cURL theme={null}
curl "https://api.modempay.com/v1/transfers/account-lookup/2007/6240000000" \
  -H "Authorization: Bearer sk_test_..."
```

```typescript json theme={null}
{
  "account_name": "John Doe",
  "account_number": "6240000000",
  "transaction_id": "9f2c1b6e-..."
}
```

| Field | What it is |
| - | - |
| `account_name` | The name on the account. |
| `account_number` | The number you looked up, echoed back. |
| `transaction_id` | A reference for this lookup. |

Show `account_name` to the user so they can confirm it matches who they meant to pay, then send the payout.

## Send a payout

```typescript nodejs theme={null}
import ModemPay from "modem-pay";

const modemPay = new ModemPay("sk_test_...");

const response = await modemPay.transfers.initiate(
  {
    amount: 100,
    currency: "GMD",
    network: "2007",
    account_number: "6240000000",
    beneficiary_name: "John Doe",
    narration: "Vendor payment for April supplies",
    metadata: {
      vendor_id: "vendor_001",
      invoice_id: "inv_204",
    },
  },
  "Idempotency-Key",
);
```

```python python theme={null}
from modempay import ModemPay

modem_pay = ModemPay(api_key="sk_test_...")

response = modem_pay.transfers.initiate(
    params={
        "amount": 100,
        "currency": "GMD",
        "network": "2007",
        "account_number": "6240000000",
        "beneficiary_name": "John Doe",
        "narration": "Vendor payment for April supplies",
        "metadata": {"vendor_id": "vendor_001", "invoice_id": "inv_204"},
    },
    idempotency_key="Idempotency-Key"
)
```

```php php theme={null}
use ModemPay\ModemPay;

$modemPay = new ModemPay('sk_test_...');

$transfer = $modemPay->transfers()->initiate([
    'amount' => 100,
    'currency' => 'GMD',
    'account_number' => '6240000000',
    'network' => '2007',
    'beneficiary_name' => 'John Doe',
    'narration' => 'Vendor payment for April supplies',
    'metadata' => [
      'vendor_id' => 'vendor_001',
      'invoice_id' => 'inv_204',
    ],
], 'Idempotency-Key');
```

```bash cURL theme={null}
curl -X POST https://api.modempay.com/v1/transfers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: Idempotency-Key" \
  -d '{
    "amount": 100,
    "currency": "GMD",
    "network": "2007",
    "account_number": "6240000000",
    "beneficiary_name": "John Doe",
    "narration": "Vendor payment for April supplies",
    "metadata": {
      "vendor_id": "vendor_001",
      "invoice_id": "inv_204"
    }
  }'

```

## What you get back

```typescript json theme={null}
{
  "id": "45eb796c-e66a-442f-bba2-d282053f8883",
  "events": {},
  "business_id": "120c298f-b736-49c1-8220-8a8c84a5d8f3",
  "account_id": "199bf17b-0b5a-45c0-a5b0-1d29f5f173c9",
  "amount": 100,
  "currency": "GMD",
  "type": "bank",
  "balance_before": 995,
  "balance_after": 894,
  "transfer_reference": "5Np7iVHrN",
  "test_mode": true,
  "status": "completed",
  "account_name": "John Doe",
  "network": "2007",
  "mobile_number": null,
  "account_number": "6240000000",
  "note": "Vendor payment for April supplies",
  "fee": 1,
  "metadata": {
    "vendor_id": "vendor_001",
    "invoice_id": "inv_204"
  },
  "updatedAt": "2025-05-05T21:12:52.839Z",
  "createdAt": "2025-05-05T21:12:52.839Z",
  "merchant_id": null,
  "recipient_business_id": null,
  "bank": "Ecobank Gambia",
  "amount_received": null,
  "otp": null
}
```

## Look up a payout

```typescript nodejs theme={null}
const transfer = await modemPay.transfers.retrieve("45eb796c...");
console.log(transfer.status); // e.g., 'completed'
```

```python python theme={null}
transfer = modem_pay.transfers.retrieve("45eb796c...")
print(transfer["status"]); # e.g., 'completed'
```

```php php theme={null}
$transfer = $modemPay->transfers()->retrieve("45eb796c...");
echo $transfer->status; # e.g., 'completed'
```

```bash cURL theme={null}
curl -X GET https://api.modempay.com/v1/transfers/45eb796c... \
  -H "Authorization: Bearer sk_test_..."
```

## Fraud checks

Every payout goes through automatic fraud checks. If one looks unusual:

* its status becomes `pending_review`;
* you get an email and a `transfer.flagged` webhook;
* no more payouts can go to that account until you review it in the dashboard.

Review flagged payouts quickly so your normal payouts aren't held up.

## Common errors

| Message | Fix |
| - | - |
| `Invalid transfer amount: … Must be at least 10.` | Send 10 GMD or more. |
| `Invalid account number format. Must be at least 7 digits` | Send only digits, no spaces or dashes. |
| `Invalid network. Must be one of: 2004, 2005, 2006, 2007, …` | Use a `code` from the [Payout channels](https://docs.modempay.com/documentation/payouts/payout-channels.md) list. |
| `Channel currently unavailable` | The channel is switched off right now. Try again later or offer another bank. |
| `Account not found` | Check the number and the channel `code`. Use [account lookup](#look-up-the-account-first-recommended) to verify. |
| `429` with a `code` such as `RATE_LIMIT` | Slow down and retry later. See [Errors](https://docs.modempay.com/documentation/errors.md#error-codes-you-may-see). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.