Initiate payout
POST
/payout
Authentication
Api-Key environment variable.Idempotency
Idempotency-Key header is automatically generated as a random UUID ({{$randomUUID}}) on each request, preventing duplicate payouts when retrying failed requests.Request Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | The payout amount to be transferred. |
currency | string | Yes | The currency code for the payout (e.g., SLE, NGN). |
payoutId | string | Yes | A unique identifier for this payout transaction . |
walletId | string | Yes | The ID of the source wallet from which funds will be debited. |
recipient.type | string | Yes | The recipient channel — either bank or wallet. |
recipient.accountDetails.name | string | Yes | Full name of the recipient. |
recipient.accountDetails.provider | string | Yes | The recipient's bank or wallet provider (e.g., ecobank, skybank, UBA, afrimoney, orange_money, qmoney). |
recipient.accountDetails.accountNumber | string | Yes | The recipient's account number. |
recipient.accountDetails.phoneNumber | string | Conditional | The recipient's phone number (required for wallet transfers). |
recipient.accountDetails.note | string | No | An optional note or payment reference. |
metadata | object | No | Optional key-value pairs for additional context or internal tracking. |
Examples
Request
Header Params
Body Params application/json
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.bokumonie.com/v2/payout' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: {{$randomUUID}}' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"amount": 10,
"currency": "SLE",
"payoutId": "{{$randomUUID}}",
"walletId": "5564222970",
"recipient": {
"type": "bank", // wallet, bank
"accountDetails": {
"name": "John Doe",
"provider": "ecobank",
"phoneNumber": null,
"accountNumber": "0427570182",
"note": "Payment for services"
}
},
"metadata": {
"key1": "value",
"key2": "value"
}
}'Response Response Example
{
"status": "Successful",
"message": "Transfer initiated successfully",
"data": {
"transaction_id": "TXN-BOK-83BD4FB5EF52C8CB2329510901",
"amount": 500,
"fee": 5,
"currency": "SLE",
"provider_response": {
"status": "Pending",
"beneficiary": "23270343533",
"provider": "ORANGE_MONEY",
"orderId": "ORD-222157C62F4FF66C",
"idempotency_key": "a634d79c-e1bf-410f-b571-77f2995f724f"
},
"payout_id": "f312c2de-af93-4e3d-a773-d5884e0d2a93",
"created_at": "2026-04-03T11:57:38.350353Z"
},
"timestamp": "2026-04-03T11:57:38.350371Z"
}Modified at 2026-04-05 14:39:10