> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Entity bank accounts ## Overview Entities that represent the customers of Monite [partners](../references/glossary#partner) can have their bank account information associated with them. These bank accounts can be set as default for payment in different currencies. ## Add a bank account to an entity To add a bank account to an entity, call [`POST /bank_accounts`](../api/entity-bank-accounts/post-bank-accounts) and provide the bank account details. All bank accounts require the `currency` and `country`. Other required fields depend on the currency and country. ### Bank accounts in Africa \[#africa] African entities can add bank accounts with any currency. Besides the required `currency` and `country` fields, all other fields and combinations thereof are allowed. **`Example: KES bank account`** ```sh Example: KES bank account curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "account_number": "1234567890", "bic": "KCBLKENXXXX", "bank_name": "KCB Bank Kenya", "display_name": "Primary account", "is_default_for_currency": true, "account_holder_name": "Macharia Kamau", "currency": "KES", "country": "KE" }' ``` ### Bank accounts in other countries \[#other-countries] In most cases, bank accounts must be located in the country where the currency is the official currency. For example: * EUR can only be chosen for bank accounts in the EU, Liechtenstein, Norway, Switzerland, and UK (including Gibraltar). * GBP can only be chosen for bank accounts in the UK (including Gibraltar). USD is an exception: entities from all countries can add USD bank accounts. > **Note** > > Currency restructions do not apply to bank accounts [in Africa](#africa). Other required fields in non-African bank accounts depend on the currency:
EUR accounts GBP accounts USD accounts in US Other currencies and countries
`iban` `country` = "UK" or "GI" `account_holder_name` `account_number` `sort_code` `account_holder_name` `account_number` `routing_number` One of: * `iban` * `account_number` and `sort_code` * `account_number` and `routing_number`
> **Info** > > * `routing_number` can be a routing number or a branch code. > * If `bic` is provided, then `iban` must also be provided. However, `iban` can be provided without `bic`. Sample request: #### EUR bank account ```sh curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "iban": "DE74500700100100000900", "bic": "DEUTDEFFXXX", "bank_name": "DEUTSCHE BANK AG", "display_name": "Primary account", "is_default_for_currency": true, "account_holder_name": "Tobias Weingart", "currency": "EUR", "country": "DE" }' ``` #### GBP bank account ```sh curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "iban": "GB15HBUK40312412345678", "bic": "HBUKGB4B", "bank_name": "HSBC UK BANK PLC", "display_name": "Primary account", "is_default_for_currency": true, "account_holder_name": "Esther Walsh", "account_number": "12345678", "sort_code": 403124, "currency": "GBP", "country": "GB" }' ``` #### US USD bank account ```sh curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "bank_name": "WELLS FARGO", "display_name": "Primary account", "is_default_for_currency": true, "account_holder_name": "Bob Jones", "account_number": "2571714302", "routing_number": "061000227", "currency": "USD", "country": "US" }' ``` The successful response returns the unique `id` assigned to the added bank account, along with other details: ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", ... } ``` ## Default bank account \[#default] Monite has a concept of "default bank account" for entities. Default bank accounts have the [`is_default_for_currency`](../api/entity-bank-accounts/get-bank-accounts-id#response.body.is_default_for_currency) field set to `true` in API responses. Default bank accounts serve several purposes: * If an entity uses [payments](../payments/index) for [accounts receivable](../accounts-receivable/index), payouts are sent to the default bank account for the appropriate currency. * Application developers can preselect the default bank account when [creating invoices](../accounts-receivable/invoices/create) and other documents. In a single-currency scenario, an entity has only one default bank account (plus optionally several non-default accounts). In multi-currency scenarios, a default bank account is set for each currency separately. For example, an entity with several GBP and EUR bank accounts has two default accounts: one for GBP and another one for EUR. ### Set the default bank account \[#set-default] The very first bank account created for each currency is automatically set as default for that currency. When [adding a new bank account](#add-a-bank-account-to-an-entity), you can explicitly mark it as default by including `"is_default_for_currency": true` in the request body. The previous default account for the same currency will no longer be default. ```sh {11} curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' -H 'Content-Type: application/json' \ -d '{ "iban": "DE74500700100100000900", "bic": "DEUTDEFFXXX", "currency": "EUR", ... "is_default_for_currency": true }' ``` You can also change the default bank account for each currency at any time by calling [`POST /bank_accounts/{bank_account_id}/make_default`](../api/entity-bank-accounts/post-bank-accounts-id-make-default): ```sh curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts/3fa8...f66afa6/make_default' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` ## Verify a bank account Bank account verification uses open banking to confirm that entity bank account details are accurate and that the account holder matches the provided information. Verification is required for certain payment methods, particularly SEPA credit transfers through payment links. To initiate verification for an entity bank account, call `POST /bank_accounts/{bank_account_id}/verify`: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts/{bank_account_id}/verify' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` The verification process uses open banking to validate bank account details. The response confirms the verification request was initiated: ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "account_holder_name": "Andreas Weingart", "currency": "EUR", "country": "DE", "is_default_for_currency": true, "open_banking_verification_status": "pending", "open_banking_verification_error": null } ``` The `open_banking_verification_status` field indicates the current verification state: * `not_verified` - Verification has not been initiated (default) * `pending` - Verification is in progress * `verified` - Bank account successfully verified * `failed` - Verification failed * `expired` - Verification expired and must be restarted * `not_applicable` - Verification is not applicable for this bank account When verification fails, `open_banking_verification_error` contains a string with details about the failure reason. This field is `null` when verification succeeds or has not been attempted. The error message is reset after a successful verification. Here is an xample response with verification error: ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "iban": "DE89370400440532013000", "open_banking_verification_status": "failed", "open_banking_verification_error": "Account holder name mismatch" } ``` Here are the possible error messages: * **"IBAN doesn't match name"** - The account holder name does not match the IBAN * **"IBAN doesn't match name. Did you mean `closeMatchName`?"** - Close match found, suggesting a similar name * **"Unknown beneficiary"** - The beneficiary account does not exist in the banking system ## List all bank accounts To get information about all bank accounts associated with the specified entity, call [`GET /bank_accounts`](../api/entity-bank-accounts/get-bank-accounts). ## Retrieve a bank account To get information about a specific bank account associated with the specified entity, call [`GET /bank_accounts/{entity_bank_account_id}`](../api/entity-bank-accounts/get-bank-accounts-id). ## Edit a bank account You can update the `account_holder_name` and `display_name` of existing entity bank accounts. To do this, call [`PATCH /bank_accounts/{entity_bank_account_id}`](../api/entity-bank-accounts/patch-bank-accounts-id) and provide the new values. To update other bank account details (for example, `iban`), you will need to delete the existing bank account and create a new one instead. > **Info** > > The `account_holder_name` of existing GBP and USD bank accounts cannot be changed to an empty string since it is a required field. ## Delete a bank account To delete an existing bank account from the list of bank accounts associated with the specified entity, call [`DELETE /bank_accounts/{entity_bank_account_id}`](../api/entity-bank-accounts/delete-bank-accounts-id). [Default bank accounts](#default) cannot be deleted. To delete a default bank account, you must first assign a new default account for the same currency.