## Link bank account to a contact

Link a bank account to a contact. This creates a new bank account record associated with the contact.

- The bank account is added to the contact's list of bank accounts
- If the contact has no bank account, this new account will automatically become the primary one
- If the `primary` parameter is set to `true`, this account will be set as the primary bank account (replacing any existing primary account)
- If the contact already has a primary bank account and `primary` is not set, this new account will be added as a secondary account

The endpoint returns a unique identifier for the bank account that you can use to reference it in other API calls.

## Endpoint signature

```http
POST https://api.reservepay.com/merchants/link-bank-account HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  contact_id: string,
  bank_code: string,
  number: string,
  name: string,
  country_code: string,
  primary: boolean?,
  external_id: string?,
}
```

Returns: string

## Request arguments

### `contact_id` (string)

**Required**. The contact ID (either internal UID or external ID) to add the bank account to.

### `bank_code` (string)

**Required**. The bank's code in your country's banking system. For example, in Thailand this would be the 3-digit bank code assigned by the Bank of Thailand.

### `number` (string)

**Required**. The bank account number. Dashes and spaces are accepted and will be stripped automatically. Only digits, dashes, and spaces are allowed.

### `name` (string)

**Required**. The account holder's name as registered with the bank.

### `country_code` (string)

**Required**. The two-letter ISO country code where the bank account is located (e.g. TH for Thailand, SG for Singapore).

### `primary` (boolean)

_Optional_. Make this account the primary one. Default: false. If true, this bank account will be set as the contact's primary bank account, replacing any existing primary account.

### `external_id` (string)

_Optional_. Your own external identifier for this bank account. This can be used to reference the bank account in other API calls instead of the internal UID.

## Errors specific to this endpoint

### `NOT_FOUND`

No contact found with the provided contact_id.

### `COUNTRY_MISMATCH`

The bank account's country code does not match your payment provider's country.

### `INVALID_BANK_CODE`

The bank code is not valid for Thailand. Bank codes must be 3-digit codes assigned by the Bank of Thailand.

## Errors common to all endpoints

### `UNHANDLED_ERROR`

This error occurs when the server encounters an unexpected internal error that
it cannot handle gracefully. This typically happens due to bugs, infrastructure
issues, or edge cases that weren't anticipated during development.

### `INVALID_ARGUMENTS`

This error occurs when the request contains invalid or missing parameters.
Common cases include missing required fields, or values that don't match the
expected format or type.

### `BAD_VERSION`

This error occurs when making requests to an API version that does not exist.
This commonly happens when using an outdated SDK or when the API version
specified in the request URL is incorrect.