Payouts

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)

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"
  }'

{
  "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
}

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:

{
  "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.

Find the bank code

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

{ "data": [{ "code": "058", "name": "Guaranty Trust Bank" }, ...], "country": "NG" }

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"
  }'

{
  "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.

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.

Pay it

{
  "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.

Get started

Essentials

Guides

Mobile money (Cameroon)

Bank accounts (Nigeria)

Withdrawing to your own account

​Mobile money (Cameroon)

​Bank accounts (Nigeria)

​Withdrawing to your own account

Mobile money (Cameroon)

Bank accounts (Nigeria)

Withdrawing to your own account