Link a bank account

POST

/v1/wallet/fiat/{currency}/accounts

Requires BANK_ACCOUNTS_MANAGE, granted by BANK_ACCOUNTS_WRITE (bundles)

Links a bank account for fiat withdrawals to the account (the primary, or the sub-account selected with X-VALR-SUB-ACCOUNT-ID). It's active straight away, with no email or two-factor confirmation; for currencies that only pay out to verified bank accounts, withdrawals to it are refused until it shows VERIFIED. Take bank from List banks for a currency; accountType is CHEQUE, SAVINGS, BOND or TRANSMISSION for South African accounts.

Parameters

Path Parameters

currency*

Fiat currency the bank account receives, e.g. ZAR.

Type

string

Required

Example"ZAR"

Request Body

application/json

{

"bank": "FNB",

"accountHolder": "Acme Trading (Pty) Ltd",

"accountNumber": "62792461544",

"branchCode": "250655",

"accountType": "CHEQUE",

"country": "ZA"

}

Responses

Accepted

Content-Type

application/json

{

"id": "b71d4e93-2a6f-4c08-8e5b-d93f1a7c2e40",

"bankCode": "FNB",

"bankName": "FNB/RMB",

"accountHolder": "Acme Trading (Pty) Ltd",

"accountNumber": "62792461544",

"branchCode": "250655",

"accountType": "Current/Cheque",

"status": "CONFIRMED",

"insertedAt": "2026-10-23T08:14:02.518236Z",

"updatedAt": "2026-10-23T08:14:02.611904Z",

"country": "ZA",

"currency": {

"symbol": "R",

"decimalPlaces": 2,

"isActive": true,

"shortName": "ZAR",

"longName": "Rand",

"supportedWithdrawDecimalPlaces": 2,

"collateral": true,

"collateralWeight": "1"

}

}

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 bank that isn't in the country's bank list or a branch code, account number or account type that doesn't fit the country, or the currency isn't recognised; validationErrors lists each failing field.
400	-15875FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED	Withdrawals to this branch code aren't supported. Use another branch or contact support.
400	-13418BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED	Linking bank accounts is paused for a while after a security change on your account, such as a password reset or a new device; the message says when it's re-enabled.
400	-115INVALID_COUNTRY_ALPHA_2	No banks are available for the bank account's country.
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 the bank account's country couldn't be loaded. Try again later.

Plus the errors common to all signed endpoints.