Open a Bank Account
Opens a deposit account for an account, in one fiat currency, at the bank your workspace uses for that currency. The bank opens it while the request waits, and the response carries the bank's account_number: the number a payer sends money to. An account can hold several bank accounts in one currency, for example one for payroll and another for reserves.
- The holder must be known to the bank. Their KYC or KYB verification has to have reached the bank, which happens once it is approved. Until then the request answers
409 bank_customer_not_onboarded. - Which currencies can be opened depends on your workspace's bank. A currency it holds no accounts in answers
422 bank_account_currency_not_supported. - Nothing is recorded when the bank refuses. A refused request creates no bank account.
- The first one becomes the default. The first bank account an account holds in a currency becomes its default (
is_default: true): money in that currency that names no bank account lands in it. Later ones do not; make one the default with Set the Default Bank Account.
The response carries no routing number or bank name. Get Deposit Instructions answers those for this bank account, with its own number, once it is active. v2's Deposit Instructions answers with the number of only one of the account's bank accounts, not necessarily this one.
A workspace-scoped key names the account with account_id; an account-scoped key acts for its own account.
Authorization:
Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.
Headers:
Authorization: APIKey {SIGNED_JWT}
How to build and sign the JWT: Authentication.
Endpoint
/v3/bank-accounts
Headers
| Header | Description |
|---|---|
Idempotency-Key | Required. One UUID per bank account you mean to open, sent again unchanged on every retry. A retry answers the first response instead of opening a second bank account. API keys have a grace period until 2027-01-18: a request without the header still runs, without that protection, and its response carries Warning: 299 - "Idempotency-Key will be required on this endpoint from 2027-01-18". Dashboard sessions are already held to it. See API v3 overview. |
Query parameters
| Parameter | Type | Description |
|---|---|---|
account_id | string (cst_…) | The account to open the bank account for. Required for a workspace-scoped key; an account-scoped key opens one for its own account and may omit it. |
Request Body Sample
{
"currency": "USD",
"name": "Payroll"
}
Request Body Schema
| Field | Type | Description |
|---|---|---|
currency | string | Required. USD, MXN, ARS, COP, BRL or NGN, in upper case. Which of them can be opened depends on your workspace's bank. |
name | string | Optional. 1 to 60 characters; leading and trailing spaces are dropped. Without a name, the bank account shows as its currency plus account, for example USD account. It can be renamed later. |
Response Sample
201 Created
{
"id": "bnk_01k8x4p6sx9t5v7x1z3b5d7f9h",
"customer_id": "cst_01h455vb4pex5vsknk084sn02q",
"kind": "deposit",
"name": "Payroll",
"reference": "K7Q2MZ",
"account_number": "555000114027",
"currency": "USD",
"status": "active",
"is_default": false,
"created_at": "2026-10-20T16:12:30Z",
"updated_at": "2026-10-20T16:12:30Z"
}
Response Schema
The new bank account, with the fields of a List Bank Accounts row:
| Field | Description |
|---|---|
account_number | The bank's number for the new account. Always present on a bank account this endpoint opens. |
status | active, or pending when the bank opened the account but has not activated it yet. |
is_default | true when this is the account's first bank account in the currency. |
Errors
| Status | message | When |
|---|---|---|
400 | account_id_required | A workspace-scoped key named no account_id. |
400 | failed to parse request | The body is not valid JSON, currency is not one of the listed codes (for example usd or BTC), or account_id is not a cst_… id. |
400 | invalid_bank_account_name | name is longer than 60 characters. |
400 | idempotency_key_required | No Idempotency-Key header, from a dashboard session, or from an API key once the grace period ends on 2027-01-18. |
400 | idempotency_key_invalid | The Idempotency-Key is longer than 255 characters or not printable ASCII. |
401 | unauthorized | Missing or invalid signature. |
403 | forbidden | An account-scoped key named another account, or account_id names no account of the workspace. |
409 | bank_provider_not_configured | Your workspace has no bank to open accounts in this currency at. Contact BlockWyre. |
409 | bank_customer_not_onboarded | The holder's verification has not reached the bank yet. Try again once their KYC or KYB is approved. |
409 | idempotency_in_progress | The same Idempotency-Key is still running. Retry after Retry-After seconds with the same key. |
413 | body_too_large | The body is over 1 MiB. |
422 | Validation failed | currency is missing; details names it. |
422 | bank_account_currency_not_supported | The bank holds no accounts in this currency, or your workspace does not offer the currency or has turned it off. |
422 | bank_account_open_rejected | The bank refused to open the account. |
422 | idempotency_key_conflict | The same Idempotency-Key was used for a different request. |
503 | idempotency_unavailable | The key store is unavailable. Nothing ran: retry later with the same key. |
Support and Resources
If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.
Stay Updated
Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:
- Instagram: BlockWyre Instagram
- Twitter: BlockWyre Twitter
- Facebook: BlockWyre Facebook
- LinkedIn: BlockWyre LinkedIn
We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!