> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bank Account Identifiers

> The identifiers a bank account needs in each country, for POST /merchants/{id}/bank-accounts

`POST /merchants/{id}/bank-accounts` adds an account the merchant owns, which Quidkey pays out to. Every account needs `currency`, `country` and `account_holder_name`. Which identifiers it needs depends on its `country`.

`GET /countries/{id}` gives what a country needs: the payment schemes an account there takes, and the rules for the details Quidkey collects. It doesn't list bank identifiers, so the table below gives what some common countries need. A create that's missing one answers 400 `BANK_DETAILS_INCOMPLETE`.

| Example | Send | Format |
| - | - | - |
| Euro-area countries, such as Germany, France, Ireland and Spain | `iban`, and optionally `bic` | IBAN: 15 to 34 letters and digits. BIC: 8 or 11 letters and digits. |
| Poland | `iban`, and optionally `bic`, with `currency` `EUR` | As for the euro area. Accounts in Poland are paid over SEPA, which carries only euros. |
| United Kingdom | `sort_code` and `account_number`, or a UK `iban` | Sort code: 6 digits. Account number: 8 digits. |
| United States | `routing_number` and `account_number` | Routing number: 9 digits. Account number: 4 to 17 digits. |
| Australia | `bsb` and `account_number` | BSB: 6 digits. Account number: 6 to 9 digits. |
| Denmark | `iban`, or the account number as `bban` | BBAN: 4 to 10 digits. There's no field for the 4-digit reg. number. |

* Send identifiers without spaces or dashes: `112233`, not `11-22-33`.
* An IBAN is checked. One that fails its checks answers 400 `BANK_DETAILS_INVALID`.
* An IBAN can address an account in another country only where both are in SEPA's scope and Quidkey pays that country over SEPA, as a Belgian IBAN for a German account. Otherwise it answers 400 `BANK_DETAILS_COUNTRY_MISMATCH`: a German IBAN can't address a UK account.
* An account in Poland, or with a Polish IBAN, in any currency but `EUR` answers 400 `BANK_ACCOUNT_CURRENCY_UNSUPPORTED`.
* A country Quidkey doesn't support for bank accounts answers 400 `COUNTRY_NOT_SUPPORTED`. A `country` that isn't an ISO 3166-1 code answers 400 `VALIDATION_FAILED` on `country`.

`iban`, `account_number`, `bban` and `plusgiro_number` are write-only. A read returns `masked_identifier`, the end of the number behind `****`, never the number itself. `bic`, `sort_code`, `routing_number` and `bsb` identify a bank, not an account, so a read returns them.

## Example

A UK account, attesting the person's authorisation of debits from it:

```json theme={null}
{
  "currency": "GBP",
  "country": "GB",
  "account_holder_name": "Example Store Ltd",
  "sort_code": "112233",
  "account_number": "12345678",
  "consent": {
    "is_accepted": true,
    "accepted_at": "2026-11-02T09:58:00.000Z",
    "accepted_by": { "full_name": "Jane Doe", "email": "jane@example.com" },
    "accepted_ip": "203.0.113.7",
    "wording": "I authorise Quidkey and its processors to debit this account for amounts due to Quidkey.",
    "locale": "en-GB",
    "agreements": [{ "id": "agr_bank_debit_authorization" }]
  }
}
```

`agreements` holds the current `bank_debit_authorization`, from `GET /agreements?kind=bank_debit_authorization`, and nothing else. `consent` is optional: leave it out to record the authorization later through `agreement_acceptance`, naming the account. See [Onboard a merchant](https://docs.quidkey.com/api-v1/journeys/onboard-a-merchant.md).

## Other Country Rules

A country's other collection rules are on `GET /countries/{id}`: which address fields Quidkey collects, its regions, its legal structures, and `field_rules` for a postal code, a registration number, a VAT number and a tax ID. Each rule gives a `label`, `min_length`, `max_length`, an ECMA-262 `pattern` and a `placeholder`, and any part can be `null`.

A legal entity's `tax_id` is held to its country's `pattern` once its separators are out, and an Australian one to its checksum as well. A `registration_number` and a `vat_number` aren't checked against their rules when you create a legal entity, though onboarding can check them, so send them without separators.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.