Create Withdrawal

Initiate a disbursement to a beneficiary's mobile wallet.

Endpoint

POST /api/withdraws/initiate

Request parameters

Parameter	Type	Required	Description
amount	Double	✅	Amount to transfer (min: 0.01)
currency	String	✅	ISO 4217 currency code (3 characters, e.g. XOF, EUR)
beneficiaryName	String	✅	Full name of beneficiary
beneficiaryPhone	String	✅	Phone number in international format (e.g. +221770000000)
beneficiaryEmail	String	❌	Beneficiary email
country	String	✅	ISO 3166-1 alpha-2 country code (e.g. SN, CI)
gatewayName	String	❌	Specific gateway (otherwise automatic selection)
callbackUrl	String	❌	Webhook URL for notifications (max 500 characters)
returnUrl	String	❌	Redirect URL after processing
metadata	Map<String, String>	❌	Custom data (e.g. orderReference, userId)

Request example

curl -X POST "https://app.awdpay.com/api/withdraws/initiate" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "beneficiaryName": "Amadou Diallo",
    "beneficiaryPhone": "+221770123456",
    "beneficiaryEmail": "amadou@example.com",
    "country": "SN",
    "gatewayName": "wave-senegal",
    "callbackUrl": "https://merchant.example/webhooks/withdrawals",
    "metadata": {
      "orderReference": "PAYOUT-8831",
      "userId": "usr_12345"
    }
  }'

Success response

{
  "reference": "WTD1704067200000ABC123",
  "status": "pending",
  "fees": 50.0,
  "paymentType": "direct",
  "createdAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T11:30:00Z",
  "message": "Withdrawal initiated successfully"
}

Response fields

Field	Type	Description
reference	String	Unique withdrawal reference (format: WTD{timestamp}{random})
status	String	Initial status (pending, processing)
fees	Double	Amount of fees charged
paymentType	String	Processing type (direct, redirect, redirect_post, ussd)
createdAt	DateTime	Creation date/time
expiresAt	DateTime	Expiration date/time
message	String	Descriptive message
url	String	Confirmation URL (if paymentType = redirect)

Error codes

HTTP Code	Error code	Description
400	invalid_request	Missing or invalid parameters
401	unauthorized	Invalid or expired token
404	merchant_not_found	Merchant account not found
422	insufficient_balance	Insufficient merchant balance
422	limit_exceeded	Transaction limit exceeded
500	server_error	Internal error

---

Next step

➡️ Check status — Track your withdrawal status