Skip to main content

​
Overview

Entities that represent the customers of Monite partners 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 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

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
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

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.
Currency restructions do not apply to bank accounts in Africa.
Other required fields in non-African bank accounts depend on the currency:
EUR accountsGBP accountsUSD accounts in USOther currencies and countries
ibancountry = “UK” or “GI”account_holder_nameaccount_numbersort_codeaccount_holder_nameaccount_numberrouting_numberOne of:
  • iban
  • account_number and sort_code
  • account_number and routing_number
  • 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: 
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"
     }'
The successful response returns the unique id assigned to the added bank account, along with other details: 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  ...
}

​
Default bank account

Monite has a concept of “default bank account” for entities. Default bank accounts have the is_default_for_currency field set to true in API responses. Default bank accounts serve several purposes:
  • If an entity uses payments for accounts receivable, payouts are sent to the default bank account for the appropriate currency.
  • Application developers can preselect the default bank account when creating invoices 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

The very first bank account created for each currency is automatically set as default for that currency. When adding a new bank account, 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. 
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: 
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'

​
List all bank accounts

To get information about all bank accounts associated with the specified entity, call 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}.

​
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} 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.
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}. Default bank accounts cannot be deleted. To delete a default bank account, you must first assign a new default account for the same currency.