## Send a payout to a contact

- **Bank account**: Provide `recipient_id` only to use the contact's primary bank account,
  or include `bank_account_id` to specify a particular account. To create a new bank account
  on the contact, omit `bank_account_id` and provide `bank_account_number`, `bank_account_name`,
  `bank_code`, and `country_code` instead. The two approaches are mutually exclusive.
- **Mobile number (PromptPay)**: Set `payout_method` to `mobile_number` and provide `mobile_number`.
  Accepts local format (e.g. `0812223333`) or E.164 (e.g. `+66812223333`).
- **National ID (PromptPay)**: Set `payout_method` to `national_id` and provide `national_id` (13 digits).

When using a bank account, it must belong to the contact and be active (not soft-deleted).

## Endpoint signature

```http
POST https://api.reservepay.com/merchants/send-payout-to-contact HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  recipient_id: string,
  payout_method: string?,
  bank_account_id: string?,
  bank_account_number: string?,
  bank_account_name: string?,
  bank_code: string?,
  country_code: string?,
  mobile_number: string?,
  national_id: string?,
  external_id: string?,
  amount: string,
  recipient_mobile: string?,
  recipient_name: string?,
  recipient_email: string?,
}
```

Returns: string

## Request arguments

### `recipient_id` (string)

**Required**. The contact ID (either internal UID or external ID) to send the payout to.

### `payout_method` (string)

_Optional_. The payout method to use. Accepted values: `bank_account`, `mobile_number`, `national_id`.

### `bank_account_id` (string)

_Optional_. The bank account ID (internal UID starting with `bka_` or your external ID) to send the payout to.
If not provided when using `bank_account`, the payout will be sent to the contact's primary bank account.
Cannot be provided together with `bank_account_number`, `bank_account_name`, `bank_code`, or `country_code`.

### `bank_account_number` (string)

_Optional_. The bank account number. Dashes and spaces are accepted and will be stripped automatically. Only digits, dashes, and spaces are allowed. Provide together with `bank_account_name`, `bank_code`, and `country_code` to create a new bank account on the contact. Cannot be used with `bank_account_id`.

### `bank_account_name` (string)

_Optional_. The bank account name. Provide together with `bank_account_number`, `bank_code`, and `country_code` to create a new bank account on the contact. Cannot be used with `bank_account_id`.

### `bank_code` (string)

_Optional_. The bank code. Provide together with `bank_account_number`, `bank_account_name`, and `country_code` to create a new bank account on the contact. Cannot be used with `bank_account_id`.

### `country_code` (string)

_Optional_. The country code (e.g. `TH`). Provide together with `bank_account_number`, `bank_account_name`, and `bank_code` to create a new bank account on the contact. Cannot be used with `bank_account_id`.

### `mobile_number` (string)

_Optional_. The recipient's mobile number for PromptPay payouts. Required when `payout_method` is `mobile_number`.
Accepts local format (e.g. `0812223333`) or E.164 format (e.g. `+66812223333`).
Dashes and spaces are accepted and will be stripped automatically (e.g. `081-222-3333`).
If no country prefix is provided, it is inferred from the provider's country.

### `national_id` (string)

_Optional_. The recipient's national ID (13 digits) for PromptPay payouts. Required when `payout_method` is `national_id`. Dashes and spaces are accepted and will be stripped automatically (e.g. `1-2345-67890-12-3`).

### `external_id` (string)

_Optional_. Your unique reference for this payout. You can use this ID later to look up the
payout instead of our payout ID. Must be unique across all your payouts.

### `amount` (string)

**Required**. The payout amount in the smallest currency unit (e.g. satang). For example,
use 10000 for 100 THB. Must be a positive integer.

### `recipient_mobile` (string)

_Optional_. The recipient's mobile number. If provided, the contact's mobile number will be updated to this value. Dashes and spaces are accepted and will be stripped automatically.

### `recipient_name` (string)

_Optional_. The recipient's name. If provided, the contact's name will be updated to this value.

### `recipient_email` (string)

_Optional_. The recipient's email address. If provided, the contact's email will be updated to this value.

## Errors specific to this endpoint

### `NOT_FOUND`

No contact found with the provided recipient_id, the bank account does not exist or does not belong to the contact, or the payout method is not configured for this merchant.

### `INVALID_OPERATION`

The contact does not have a primary bank account. Please specify a bank_account_id.

### `INSUFFICIENT_BALANCE`

The merchant does not have sufficient balance to complete this payout.
The requested amount exceeds the available balance in the merchant's account.

### `INVALID_MOBILE_NUMBER`

The mobile number must be a valid local number (e.g. 0812223333) or E.164 number (e.g. +66812223333).

### `INVALID_NATIONAL_ID`

The national ID must be exactly 13 digits.

### `INVALID_AMOUNT`

The payout amount exceeds the merchant or payout method limits.

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