Entity bank accounts

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 country and currency.

In most cases, bank accounts must be located in the country where the currency is the official currency. For example:

• USD can only be chosen for bank accounts in the US.
• GBP can only be chosen for bank accounts in the UK (including Gibraltar).
• EUR can only be chosen for bank accounts in the EU, Liechtenstein, Norway, Switzerland, and UK (including Gibraltar).

Other required fields in bank accounts depend on the currency:

Sample request:

1
curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "iban": "DE74500700100100000900",
8
       "bic": "DEUTDEFFXXX",
9
       "bank_name": "DEUTSCHE BANK AG",
10
       "display_name": "Primary account",
11
       "is_default_for_currency": true,
12
       "account_holder_name": "Tobias Weingart",
13
       "currency": "EUR",
14
       "country": "DE"
15
     }'

The successful response returns the unique id assigned to the added bank account, along with other details:

1
{
2
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3
  "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4
  ...
5
}

Set the default bank account

Once the bank accounts are added to the entity, set a default bank account for each currency by calling POST /bank_accounts/{bank_account_id}/make_default:

1
curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts/3fa8...f66afa6/make_default' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts/{bank_account_id}/verify' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

The verification process uses open banking to validate bank account details. The response confirms the verification request was initiated:

1
{
2
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3
  "iban": "DE89370400440532013000",
4
  "bic": "COBADEFFXXX",
5
  "account_holder_name": "Andreas Weingart",
6
  "currency": "EUR",
7
  "country": "DE",
8
  "is_default_for_currency": true,
9
  "open_banking_verification_status": "pending",
10
  "open_banking_verification_error": null
11
}

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:

1
{
2
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3
  "iban": "DE89370400440532013000",
4
  "open_banking_verification_status": "failed",
5
  "open_banking_verification_error": "Account holder name mismatch"
6
}

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.

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.

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