> This page is for version v2024-05-25 (default).
> For other versions, use one of these documentation indexes:
> - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt
> - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt
> - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt

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

# Counterpart bank accounts

## Overview

[Counterparts](./index) that represent an [entity's](../../entities/index) vendors or suppliers can have bank account information associated with them. The bank account information can be used to pay the invoices ([payables](../../accounts-payable/payables/collect)) issued by those counterparts.

## Add a bank account to a counterpart

To add a bank account to a counterpart, call [`POST /counterparts/{counterpart_id}/bank_accounts`](/api/counterpart-bank-accounts/post-counterparts-id-bank-accounts) and provide the bank account details.

All bank accounts require the `currency` and `country`. Other necessary fields depend on the country and the type of fund transfers - domestic or international.

| International transfers | EU banks     | UK banks                                                        | US banks                                                                 |
| ----------------------- | ------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `iban` `bic`            | `iban` `bic` | `account_number` `sort_code` `iban` (optional) `bic` (optional) | `account_holder_name` `account_number` `routing_number` `bic` (optional) |

Sample requests:

#### IBAN + BIC

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/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",
       "account_holder_name": "Tobias Weingart",
       "name": "Primary account",
       "currency": "EUR",
       "country": "DE",
       "is_default_for_currency": false
     }'
```

#### UK bank

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/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",
       "account_number": "12345678",
       "sort_code": "403124",
       "account_holder_name": "Esther Walsh",
       "name": "Primary account",
       "currency": "GBP",
       "country": "GB",
       "is_default": true
     }'
```

#### US bank

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/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": "2571714302",
       "routing_number": "061000227",
       "account_holder_name": "Bob Jones",
       "name": "Primary account",
       "currency": "USD",
       "country": "US",
       "is_default": true
     }'
```

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

```json
{
  "id": "04476eb4-121e-44dd-8a0d-1bcaa9246265",
  "counterpart_id": "3a9c5924-2c3f-47af-905a-e4c7efe548df",
  "is_default_for_currency": false,
  "partner_metadata": {},
  ...
}
```

## Set the default bank account

Once the bank accounts are added to a counterpart, you can set a default bank account for each currency by making a `POST` request to the `/counterparts/{counterpart_id}/bank_accounts/{bank_account_id}/make_default` endpoint:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/{counterpart_id}/bank_accounts/{bank_account_id}/make_default' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

The successful response contains information about the counterpart's bank account marked as default:

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "iban": "GB33BUKB20201555555555",
  "bic": "GB33BUKB202",
  "bank_name": "Bank name",
  "is_default_for_currency": true,
  "display_name": "My main account",
  "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "account_holder_name": "Mary O Brien",
  "account_number": "123456789",
  "routing_number": null,
  "sort_code": null,
  "currency": "EUR",
  "country": "DE"
}
```

> **Note**
>
> The default counterpart bank account is set for each currency. Each counterpart can only have one default bank account per currency. The `is_default_for_currency` field indicates which bank accounts are the default for each currency.
>
> If a new counterpart bank account is added to a currency with no default bank account set, the newly added bank account is automatically set as the default for that currency.

## Verify a counterpart 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 a counterpart bank account, call `POST /counterparts/{counterpart_id}/bank_accounts/{bank_account_id}/verify`:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/{counterpart_id}/bank_accounts/{bank_account_id}/verify' \
  -H 'X-Monite-Version: 2024-05-25' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-monite-entity-id: ENTITY_ID'
```

The verification process uses open banking to validate the 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": "Mary O Brien",
  "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 example 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 counterpart, call\
[`GET /counterparts/{counterpart_id}/bank_accounts`](/api/counterpart-bank-accounts/get-counterparts-id-bank-accounts).

## Retrieve a bank account

To get information about a specific bank account associated with the specified counterpart, call\
[`GET /counterparts/{counterpart_id}/bank_accounts/{bank_account_id}`](/api/counterpart-bank-accounts/get-counterparts-id-bank-accounts-id).

## Edit a bank account

To edit an existing bank account of the specified counterpart, call\
[`PATCH /counterparts/{counterpart_id}/bank_accounts/{bank_account_id}`](/api/counterpart-bank-accounts/patch-counterparts-id-bank-accounts-id).

## Delete a bank account

To delete an existing bank account from the list of bank accounts associated with the specified counterpart, call\
[`/counterparts/{counterpart_id}/bank_accounts/{bank_account_id}`](/api/counterpart-bank-accounts/delete-counterparts-id-bank-accounts-id). Only non-default bank accounts can be deleted.