--- title: "Create a bank account for a merchant" method: POST path: "/api/v1/merchants/{id}/bank-accounts" tags: ["Merchant Bank Accounts"] --- # Create a bank account for a merchant `POST /api/v1/merchants/{id}/bank-accounts` ## Request - Base URL: `https://core.quidkey.com` - URL: `https://core.quidkey.com/api/v1/merchants/{id}/bank-accounts` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a bank account for a merchant ## Path parameters - `id` string, uuid, required: The unique identifier of the merchant ## Request body - MerchantBankAccountCreateInput: Merchant bank account creation input (direct-debit authorization evidence required for user-auth callers) - `account_number` string: The account number or IBAN of the bank account - `currency` string, required: The currency of the bank account - `country` string, required: The country of the bank account - `iban` string: The IBAN of the bank account (for EU market) - `bic` string: The BIC of the bank account (for EU market) - `sort_code` string: The sort code of the bank account (for UK market) - `routing_number` string: The routing number of the bank account (for US market) - `bank_id` string, uuid: The optional unique identifier of the associated bank entity - `bban` string: Basic Bank Account Number (e.g., for Norway) - `plusgiro_number` string: PlusGiro number (for Sweden) - `bsb` string: Bank State Branch code (for Australia) - `account_holder_name` string: Name of the account holder - `supported_payment_schemes` object[]: Optional array of payment schemes with active status. If omitted, no payment schemes will be attached. - `type` union, required: The type of payment scheme - 'SEPA_CREDIT_TRANSFER' - 'MULTIBANCO' - 'DANISH_DOMESTIC_CREDIT_TRANSFER' - 'FASTER_PAYMENTS' - 'BACS' - 'BECS' - 'ACH' - `is_active` boolean: Whether this account should actively receive payments for this scheme. Defaults to false if not specified. - `client_evidence` object - `checkout_page_version` string: APP_COMMIT_SHA the page was built from - `timezone` string: Browser IANA timezone - `fingerprint` string: FingerprintJS visitor id if available - `consented_agreements` object[], required: One entry per required consent kind for the current acceptance - `kind` string, required: AgreementKind literal - `agreement_id` string, uuid, required - `checkbox_language` object[], required: Rendered text of each checkbox the user ticked - `checkbox_id` string, required - `rendered_text` string, required - `covers_kinds` string[], required ## Response `201` Created - MerchantBankAccountResponse - `success` boolean, required: Indicates if the request was successful - `data` object, required: Merchant bank account information - `id` string, uuid: The unique identifier of the bank account - `account_number` string: The account number or IBAN of the bank account - `currency` string: The currency of the bank account - `country` string: The country of the bank account - `status` union: The status of the bank account - 'active' - 'archived' - `account_information_session_id` string, uuid: The account information session ID that created this bank account when linked via provider flow - `created_at` string, date-time: The creation date of the bank account - `updated_at` string, date-time: The last update date of the bank account - `iban` string: The IBAN of the bank account (for EU market) - `bic` string: The BIC of the bank account (for EU market) - `sort_code` string: The sort code of the bank account (for UK market) - `routing_number` string: The routing number of the bank account (for US market) - `bban` string: Basic Bank Account Number (e.g., for Norway) - `plusgiro_number` string: PlusGiro number (for Sweden) - `bsb` string: Bank State Branch code (for Australia) - `account_holder_name` string: Name of the account holder - `supported_payment_schemes` object[]: Payment schemes this account supports - `id` string, uuid, required: The unique identifier of the payment scheme - `type` union, required: The type of payment scheme - 'SEPA_CREDIT_TRANSFER' - 'MULTIBANCO' - 'DANISH_DOMESTIC_CREDIT_TRANSFER' - 'FASTER_PAYMENTS' - 'BACS' - 'BECS' - 'ACH' - `name` string, required: Human-readable name of the payment scheme - `is_active` boolean, required: Whether this account actively receives payments for this scheme - `additional_payment_method` boolean, required: Whether this scheme appears as a separate payment option in UI - `roles` union[]: The purposes this account serves - union: The purpose an account serves - 'receiving' - 'settlement' - 'refund' - `balance` string: Current balance for accounts that support balance reporting (decimal string) ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `500`: Internal Server Error ## Changes - **2026-06-17** `b372e7d5563d`: 5 breaking, 3 warning, 10 info - the `country` request property's minLength was increased from `0` to `2` - the `currency` request property's minLength was increased from `0` to `3` - added the pattern `^[A-Za-z]{2}$` to the request property `country` - added the pattern `^[A-Za-z]{3}$` to the request property `currency` - …14 more - **2025-11-05** `6637b341d86d`: 1 info - endpoint added - **2025-11-02** `919eb7a392aa`: 1 breaking - api path removed without deprecation [Operation history](https://skmtc.dev/banqzinc/apis/quidkey-api/changes/api/v1/merchants/:id/bank-accounts/post.md) --- [API](https://skmtc.dev/banqzinc/apis/quidkey-api.md) - [All operations](https://skmtc.dev/banqzinc/apis/quidkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/banqzinc/apis/quidkey-api/revisions/f86d2bdbcb08?raw)