Skip to main content
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.
  • 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:
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.

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.