Appearance
Pay a bank beneficiary​
POST
/v2/fiat/payments
Requires WITHDRAWALS_CREATE, granted by WITHDRAWALS_WRITE (bundles)
Pays a bank beneficiary from the account (the primary, or the sub-account selected with X-VALR-SUB-ACCOUNT-ID) straight away, with no approval step: the one-call alternative to linking a bank account and then using Withdraw fiat to a bank account. Send beneficiaryId to pay a bank account already linked to that account, or newBeneficiary (the fields of Link a bank account) to link one and pay it in the same call; currency defaults to ZAR, the fee is charged on top of amount, and borrowing isn't available. The response holds the withdrawal's id; track it with Get a fiat withdrawal.
Request Body​
application/json
JSON
{
"amount": "2500.00",
"currency": "ZAR",
"newBeneficiary": {
"bank": "STANDARD",
"accountHolder": "Karoo Logistics (Pty) Ltd",
"accountNumber": "10094857261",
"branchCode": "051001",
"accountType": "CHEQUE",
"country": "ZA"
},
"fast": true,
"reference": "INV 2026-0187"
}
Responses​
Accepted
application/json
Samples​
Errors
| HTTP | Error | When |
|---|---|---|
| 400 | -113INVALID_JSON | The body isn't valid JSON. |
| 400 | -11INVALID_REQUEST | The body is empty or a field fails validation, including a newBeneficiary field or a newBeneficiary.bank that isn't in the country's bank list, or reference was rejected; validationErrors lists each failing field. |
| 400 | -109INVALID_CURRENCY_SYMBOL | currency isn't a recognised currency. |
| 400 | -18104PAYMENT_BENEFICIARY_DETAILS_REQUIRED | Neither beneficiaryId nor newBeneficiary was sent. |
| 400 | -115INVALID_COUNTRY_ALPHA_2 | No banks are available for newBeneficiary's country. |
| 400 | -13418BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED | Adding a beneficiary is paused for a while after a security change on your account; the message says when it's re-enabled. You can still pay an existing beneficiary. |
| 400 | -15875FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED | Payments to the beneficiary's branch code aren't supported. Use another bank account or contact support. |
| 400 | -13415WITHDRAWALS_TEMPORARILY_SUSPENDED | Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled. |
| 400 | -32765WITHDRAWAL_RESTRICTION_APPLIED | The payment would take your portfolio below the minimum value it must keep. |
| 400 | -15307FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM | amount is below the minimum withdrawal for this currency. |
| 400 | -15318FIAT_WITHDRAWAL_CURRENCY_MISMATCH | The beneficiary's bank account was linked for a different currency from currency. |
| 400 | -6INSUFFICIENT_BALANCE | The account's available balance doesn't cover amount plus the fee. |
| 400 | -15309CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT | This currency only pays out to verified bank accounts, and the beneficiary hasn't been verified yet or failed verification. |
| 404 | -18106PAYMENTS_API_DISABLED | This endpoint isn't available yet. |
| 404 | -14203COULD_NOT_GET_LINKED_ACCOUNT | No bank account with beneficiaryId exists. |
| 409 | -18103PAYMENT_BENEFICIARY_NOT_ACTIVE | The beneficiary with beneficiaryId was never confirmed or has been deleted. |
| 451 | -15320FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY | Your business's region doesn't allow withdrawals in this currency. |
| 500 | -15317BANK_REMOTE_FETCH_FAILURE | The bank list for newBeneficiary's country couldn't be loaded. Try again later. |
| 503 | -12015WITHDRAWALS_NOT_AVAILABLE | Withdrawals are unavailable at the moment. Try again later. |
Plus the errors common to all signed endpoints.