Initiate Withdrawal

POST

/api/v1/merchants/withdrawals

Initiate a withdrawal (unified endpoint).

Two methods:

To saved payment account: Provide payment_account_id

To ad-hoc recipient: Provide payout_type + recipient_details

Recipient details for bank transfer:

recipient_name (required)

bank_account_number (required)

bank_name (required)

account_holder_name (required)

bank_routing_number (optional)

recipient_email (optional)

recipient_phone (optional)

Recipient details for mobile money:

recipient_name (required)

mobile_number (required)

network_provider (required: mtn_momo, mpesa, orange_money, vodafone_cash)

recipient_email (optional)

recipient_phone (optional)

Request

Authorization

Add parameter in header

x-api-key

Example:

x-api-key: ********************

Header Params

Body Params application/json

Examples

Responses

🟢200OK

application/json

Successful Response

Body

🟠422Parameter Error

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/api/v1/merchants/withdrawals' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 20000,
    "currency_code": "NGN",
    "notes": "Monthly payout",
    "payment_account_id": "e0589beb-723c-48a1-8146-a9eae60aca00"
}'

Response Example

200 - Example 1

{}

Modified at 2025-10-20 10:16:24

Delete Payment Account

Get Withdrawal History