Step 5: Withdrawal Request

Withdraw funds using the card token and customer reference ID.

Endpoint

POST /api/v1/payment/withdrawal

Description

The withdrawal process works as follows:

• First, the system attempts to process a refund from previous deposits.
• If the refund is successful, the refund amount is applied.
• Any remaining balance is sent as a payout transaction.

Request Body

{
"merchantAaccountId": "{{yourMerchantAccountId}}",
"customerReferenceId": "b86c68e5-9a14-4e49-b55e-e7f2285110a9",
"cardToken": "b1fbc631-8089-4000-806c-4984adacb3b3",
"reference": "BYOCJXEBFR18",
"currency": "USD",
"amount": "125"
}

Response Example

{
"success": true,
"message": "success",
"data": []
}

---

Webhook Notification

Once the withdrawal is processed, the system sends a status notification to your webhookUrl.

Sample Webhook Response

{
"status": "success",
"type": "withdrawal",
"reference": "BYOCJXEBFR18",
"amount": "125.00",
"currency": "USD",
"created_at": "2026-01-21T12:21:15.000000Z",
"responses": [
  {
    "solution_name": "Card Payout",
    "transaction_id": "WP12345678",
    "amount": "125.0000",
    "transaction_type": "payout",
    "status": "success"
  }
]
}

Status Reference

Status	Description
PENDING	The transaction is being processed.
SUCCESSFUL	The funds have been successfully sent.
FAILED	The transaction could not be completed. Check the error message for details.

---

Final Notes

• Webhooks are sent after final processing.
• Always validate the reference before updating your records.
• Use unique reference values for each withdrawal request.