Create Withdrawal

Create a withdrawal request for the authenticated account. The request can use the account's own Bank details or provide payout details for an MMA-authorized external recipient.

This feature is available to verified WiPay accounts and is not limited to BUSINESS accounts. Availability depends on the withdrawal type, the selected currency, the available balance, and the required payout details.

Endpoint

POST /withdrawals

Access	Requirement
Authenticated	Yes
Required Scope	`wapi-withdrawals-create`, or `wapi-withdrawals-all`
Rate Limit	15 requests per minute

Request

Headers

Header	Value
`Accept`	`application/json`
`Authorization`	`Bearer <access_token>`
`X-WAPI-Key`	`wapi_live_<kid>_<secret>` or `wapi_test_<kid>_<secret>`

Send exactly one of Authorization or X-WAPI-Key.

Body (form-data)

Required For All Withdrawal Types

Parameter	Type	Required	Description
`withdrawal_type`	string	Yes	One of `normal`, `sub_banked`, or `sub_unbanked`. See Withdrawal Meta
`currency`	string	Yes	A supported platform currency
`amount`	numeric	Yes	Withdrawal amount. WiPay normalizes the value to money format and enforces a minimum amount based on the selected currency

Additional Parameters For MMA-Authorized External Recipient Withdrawals

Use these fields when withdrawal_type is sub_banked or sub_unbanked.

Parameter	Type	Required	Description
`email`	string	Yes	Recipient email address
`phone`	string	Yes	Recipient phone number in E.164 format
`bank_name`	string	Yes	Bank name from Withdrawal Meta
`name_in_bank`	string	Yes	Recipient name as it appears on the Bank account. WiPay normalizes this value before processing
`bank_account`	string	Yes	Numeric Bank account number. Length rules depend on the selected Bank
`id_type`	string	Yes	One of `driver_permit`, `national_id`, or `passport`
`id_number`	string	Yes	Identification value validated against the selected `id_type` and platform

Jamaica-Only Additional Parameters For MMA-Authorized External Recipient Withdrawals

Use these additional fields when withdrawal_type is sub_banked or sub_unbanked on Jamaica JM platform.

Parameter	Type	Required	Description
`bank_account_type`	string	Yes	`chequing` or `savings`
`bank_branch`	string	Yes	Branch string returned by Withdrawal Meta for the selected Bank

Withdrawal Types

The sub_banked and sub_unbanked values are part of the API design. They identify how the withdrawal is processed, not whether the recipient is inherently "banked" or "unbanked" in a business sense.

`normal`

Uses the authenticated account's own Bank details.

Local-currency withdrawals require local Bank details to already be configured on the account
Foreign-currency withdrawals require foreign Bank details to already be configured on the account
Recipient Bank and identity fields are not submitted in the request

`sub_banked`

Creates an MMA-authorized withdrawal for an external recipient whose payout Bank details are supplied in the request.

The recipient does not need to already exist as a WiPay user
The MMA is responsible for the request because this flow is available only through authenticated WAPI calls
Funds are settled to the Bank account submitted in the API request, not to the authenticated MMA's Bank account

`sub_unbanked`

Creates an MMA-authorized withdrawal for an external recipient without creating a Bank transaction record.

The API still requires recipient identity and payout fields submitted by the authenticated MMA
The recipient does not need to already exist as a WiPay user
On success, the response includes a reference UUID that can be used to track the request

Operational Behavior

The authenticated account must be verified before a withdrawal can be created
The account must have sufficient balance in the selected currency
The withdrawal fee depends on withdrawal_type, currency, and platform
External-recipient withdrawal requests are wholly the responsibility of the authenticated MMA that submits them
On success, the API returns a withdrawal record and deducts the amount from the authenticated account balance

Responses

201 Created

Normal or external-recipient Bank account withdrawal

{
  "message": "Created",
  "data": {
    "reference": null,
    "transaction_id": "SB-47-1-W12345-20250306010101"
  }
}

External-recipient tracked withdrawal

{
  "message": "Created",
  "data": {
    "reference": "7d5d8d65-71de-41e5-8fb1-3f9a3b3a2749",
    "transaction_id": "SB-47-1-W12345-20250306010101"
  }
}

Field	Type	Description
`data.transaction_id`	string	Public transaction identifier for the created withdrawal
`data.reference`	string \| null	UUID reference for `sub_unbanked` withdrawals. `null` for `normal` and `sub_banked`

400 Bad Request

Insufficient funds

{
  "message": "Insufficient USD funds."
}

Missing Bank configuration for normal withdrawal

{
  "message": "Please update your USD Bank details before proceeding."
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "message": "Please verify your account before proceeding."
}

Example

Normal withdrawal

curl -X POST https://ttsb.wipayfinancial.com/wapi/withdrawals \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -F "withdrawal_type=normal" \
  -F "currency=USD" \
  -F "amount=100.00"

External-recipient Bank account withdrawal (sub_banked)

curl -X POST https://ttsb.wipayfinancial.com/wapi/withdrawals \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -F "withdrawal_type=sub_banked" \
  -F "currency=USD" \
  -F "amount=100.00" \
  -F "email=recipient@example.com" \
  -F "phone=+18687778899" \
  -F "bank_name=First Citizens" \
  -F "name_in_bank=TEST RECIPIENT" \
  -F "bank_account=1234567890" \
  -F "id_type=passport" \
  -F "id_number=TB963809"

On this page