Business API

Appearance

List fiat withdrawals​

GET
/v1/wallet/fiat/{currency}/withdrawals

Requires WITHDRAWALS_READ, granted by TREASURY_READ or TREASURY_WRITE or WITHDRAWALS_WRITE or BANK_ACCOUNTS_WRITE (bundles)

Lists fiat withdrawals in this currency, newest first, for the account (the primary, or the sub-account selected with X-VALR-SUB-ACCOUNT-ID). total counts every match across pages; use it with limit and offset to page.

Parameters​

Path Parameters

currency*

Fiat currency of the withdrawals, e.g. ZAR.

Type
string
Required
Example"ZAR"

Query Parameters

status

Only return withdrawals with this status: NEW (created, nothing done yet), PENDING_APPROVAL (waiting for an approver), PROCESSING (debited and on its way to the bank), PAID, REVERSED (paid, then returned), FAILED (didn't complete and wasn't reversed) or DECLINED (declined in review or approval). A reversed withdrawal shows FAILED until the reversal completes. Leave it out for every status.

Type
string
Example"PAID"
limit

Maximum number of withdrawals to return, from 1 to 200; values outside that range are adjusted.

Type
integer
Example50
Default
50
offset

Number of withdrawals to skip, for paging. Negative values count as 0.

Type
integer
Example0
Default
0
includeAllSubAccounts

true to include withdrawals from the primary and every sub-account apart from hidden ones. Only applies when you don't send X-VALR-SUB-ACCOUNT-ID and the key isn't restricted to sub-accounts; otherwise it's ignored.

Type
boolean
Exampletrue
Default
false

Responses​

OK

application/json
JSON
{
"items": [
{
"id": "d4a7c2e9-61f3-4b8d-9e05-7c1b3f6a2d84",
"subAccountId": "0",
"currency": "ZAR",
"amount": "1500.00",
"status": "PAID",
"linkedBankAccountId": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15",
"isFast": false,
"createdAt": "2026-10-23T08:30:05.272523Z",
"updatedAt": "2026-10-23T11:02:41.167902Z",
"feeAmount": "8.50"
},
{
"id": "5e9b3f17-a2c4-4d6e-8b91-0f4d7a2c6e33",
"subAccountId": "0",
"currency": "ZAR",
"amount": "420.00",
"status": "FAILED",
"linkedBankAccountId": "8f2a6d10-c3e4-4b7f-a915-2e7c0b9d4f68",
"isFast": true,
"createdAt": "2026-10-20T14:12:44.091355Z",
"updatedAt": "2026-10-20T14:40:18.630117Z",
"feeAmount": "25.00",
"failureReason": "INVALID_ACCOUNT_DETAILS",
"failureReasonDescription": "The bank could not find an account with these details.",
"failureReasonAction": "Check the account number, branch code and account type, update your bank account and try again.",
"failureRetryable": false
}
],
"total": 2,
"limit": 50,
"offset": 0
}

Samples​

Errors

HTTPErrorWhen
400-11INVALID_REQUESTstatus is empty or isn't one of the listed values, limit or offset isn't a whole number, includeAllSubAccounts isn't true or false, or the currency isn't recognised.

Plus the errors common to all signed endpoints.