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

# Payouts

> Send money from your balance to a mobile money wallet or a bank account.

A **payout** sends money from your **available** balance: to a supplier, a
rider, a seller on your marketplace. One Pay's fee comes on top of the
amount: sending 5 000 XAF with a 125 XAF fee uses 5 125 XAF of your balance.

The amount plus fee is **reserved** the moment the payout is created, so it
cannot be spent twice. If the payout fails, it returns to your available
balance.

```
pending → processing → succeeded
                    ↘ failed (money returned)
```

## Mobile money (Cameroon)

```bash theme={null}
curl https://onepay-api-eiy9.onrender.com/v1/payouts \
  -H "Authorization: Bearer $ONEPAY_KEY" \
  -H "Idempotency-Key: rider-week-43-paul" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "method": "mobile_money",
    "recipient": { "phone": "+237670000002", "name": "Rider Paul" },
    "reference": "rider-week-43"
  }'
```

```json theme={null}
{
  "id": "po_252af77d08b74e4b93e961c431a0db89",
  "status": "processing",
  "amount": 5000,
  "fee": 125,
  "total_debited": 5125,
  "currency": "XAF",
  "method": "mobile_money",
  "recipient": { "id": null, "phone": "+237670000002", "name": "Rider Paul" },
  "reference": "rider-week-43",
  "description": null,
  "metadata": {},
  "failure": null,
  "mode": "test",
  "created_at": "2026-10-29T09:51:37.188Z",
  "updated_at": "2026-10-29T09:51:37.275Z",
  "succeeded_at": null,
  "failed_at": null
}
```

> [!TIP]
>
> Send XAF payouts in multiples of 10 francs: some operators refuse other
> amounts.

If your available balance is lower than the amount plus fee, nothing is
created:

```json theme={null}
{
  "error": {
    "code": "insufficient_funds",
    "message": "not enough available balance: this payout needs 9225000 XAF (amount plus fee), 4575 is available",
    "request_id": "req_6b372c76b6baa259e41b97e3"
  }
}
```

## Bank accounts (Nigeria)

A Nigerian bank account is registered once, then checked by the payment
partner before it can be paid.

**1. Find the bank code**

```bash theme={null}
curl "https://onepay-api-eiy9.onrender.com/v1/banks?country=NG" \
  -H "Authorization: Bearer $ONEPAY_KEY"
```

```json theme={null}
{ "data": [{ "code": "058", "name": "Guaranty Trust Bank" }, ...], "country": "NG" }
```

**2. Register the account**

```bash theme={null}
curl https://onepay-api-eiy9.onrender.com/v1/payout_recipients \
  -H "Authorization: Bearer $ONEPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "bank_code": "058",
    "account_number": "0123456789",
    "name": "Supplier Ltd"
  }'
```

```json theme={null}
{
  "id": "rcp_18b7a5672aad4155abbfe4b97431d8f9",
  "type": "bank_account",
  "currency": "NGN",
  "bank_code": "058",
  "account_number_last4": "6789",
  "name": "Supplier Ltd",
  "account_name": "Supplier Ltd",
  "status": "approved",
  "status_reason": null,
  "mode": "test",
  "created_at": "2026-10-29T09:51:37.652Z"
}
```

`account_name` is the holder's name as the bank reports it: compare it
with who you mean to pay. Registering the same account again returns the
same recipient. The full number is never shown again.

**3. Wait for approval**

`status` is `pending_review`, then `approved` or `rejected` (with
`status_reason`). Listen for the `payout_recipient.approved` webhook, or
read `GET /v1/payout_recipients/{id}`. Test accounts are approved at once.

**4. Pay it**

```json theme={null}
{
  "amount": 500000,
  "currency": "NGN",
  "method": "bank_transfer",
  "recipient": { "id": "rcp_18b7a5672aad4155abbfe4b97431d8f9" }
}
```

A recipient not yet approved is refused with `409 recipient_not_approved`.

## Withdrawing to your own account

To move your balance to **your own** wallet or bank account, use
**Settlement** in the dashboard rather than the API: your accounts are
checked by One Pay once, then each withdrawal is confirmed with a code from
your authenticator app.


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