POST/v1/payouts/request

Request withdrawal

Requests a withdrawal from your Watenga balance to bank or agent cash.

Authentication

Secret Key — send Authorization: Bearer YOUR_KEY header.

Feature required

Requires payouts enabled on your API app. Requires 2FA (X-TOTP-Code header) if enrolled.

Request parameters

Parameter	Type	Required	Description
`amount`	string	Yes	Withdrawal amount ("10.00" format)
`currency`	string	Yes	USD or ZWG
`method`	string	Yes	bank_transfer \| agent_cash \| mobile_money
`bank_account_id`	string	No	Saved bank account UUID; fills bank/mobile fields automatically
`bank_name`	string	No	Required for bank_transfer when bank_account_id is not given
`bank_account_number`	string	No	Required for bank_transfer when bank_account_id is not given
`bank_account_name`	string	No	Required for bank_transfer when bank_account_id is not given
`bank_branch_code`	string	No	Required for non-NMB bank transfers
`mobile_money_provider`	string	No	ecocash \| onemoney \| innbucks (required for mobile_money)
`mobile_money_number`	string	No	Recipient wallet number (required for mobile_money)

For bank_transfer, send either bank_account_id or the bank_name/bank_account_number/bank_account_name fields. For mobile_money, send mobile_money_provider and mobile_money_number.

Response fields

Field	Type	Description
`payout_id`	string	Payout request ID
`method`	string	bank_transfer \| agent_cash \| mobile_money
`amount`	string	Gross withdrawal amount
`fee`	string	Payout fee
`net_amount`	string	Amount after fee
`currency`	string	USD or ZWG
`status`	string	processing on success
`expected_settlement`	string	Estimated settlement window
`agent_otp`	string	Cash-out OTP (agent_cash only)

Code examples

bash

curl -X POST https://api.watenga.africa/v1/payouts/request \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TOTP-Code: 123456" \
  -d '{
        "amount": "100.00",
        "currency": "USD",
        "method": "bank",
        "destination_id": "ba_01"
      }'

Response example

json

{
  "success": true,
  "data": {
    "payout_id": "po_01HQ",
    "method": "bank_transfer",
    "amount": "100.00",
    "fee": "1.50",
    "net_amount": "98.50",
    "currency": "USD",
    "status": "processing",
    "expected_settlement": "1-2 business days"
  }
}