## Overview

Reservepay allows you to send payouts from your merchant balance to your own bank account or directly to your contacts. This guide covers how to manage your balance, set up payout destinations, and initiate transfers.

## Managing your balance

Payouts come out of your available balance. Check it with `merchants/get-balance`, which returns the amount you can send right now. To see funds that are still on hold, see [Balance and holds](/guides/reconciliation#balance-and-holds).

### Payout methods

You can send funds in two main ways:

1. **To your primary bank account**: Typically used for settling your own merchant funds.
2. **To a contact**: Send funds directly to a customer or partner via bank account, mobile number (PromptPay), or National ID (PromptPay).

Each API call sends one payout. To pay many recipients, send one call per recipient, each with its own `external_id`.

## Sending payouts to your primary bank account

To receive funds into your own bank account, you must have configured a primary bank account during merchant onboarding.

### Initiate a payout

Once your primary bank account is set, you can send funds using `merchants/send-payout`.

Give each payout a unique `external_id`, and send the same `external_id` again if you retry it. A retry then returns the original payout instead of paying twice. See [Idempotency and timeouts](/guides/calling-api-endpoints#idempotency-and-timeouts).

```bash
curl -X POST https://api.reservepay.com/merchants/send-payout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": "10000",
    "external_id": "payout_001"
  }'
```

## Sending payouts to contacts

You can send funds directly to your contacts using `merchants/send-payout-to-contact`. The recipient must already be a contact. Create one with `merchants/add-contact` (see [Customer intelligence](/guides/customer-intelligence)), then pass its contact ID, or your own `external_id` for the contact, as `recipient_id`.

### Payout destinations for contacts

When sending to a contact, you can specify the destination in several ways:

- **Bank account**: Use the contact's primary bank account by providing only the `recipient_id`.
- **Specific bank account**: Provide both `recipient_id` and `bank_account_id`.
- **New bank account**: Provide bank details (`bank_account_number`, `bank_account_name`, `bank_code`, `country_code`) to create and use a new account for the contact.
- **Mobile number (PromptPay)**: Set `payout_method` to `mobile_number` and provide the `mobile_number` as a 10-digit local number beginning with `0` (for example `0812223333`) **or** E.164 (for example `+66812223333`).
- **National ID (PromptPay)**: Set `payout_method` to `national_id` and provide the `national_id` (exactly 13 digits).

Reservepay checks that a destination is correctly formatted, but it doesn't check who owns the account. Confirm the account details with the recipient before you send the first payout.

### Example: Sending to a contact's mobile number

```bash
curl -X POST https://api.reservepay.com/merchants/send-payout-to-contact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "recipient_id": "ctc_12345",
    "payout_method": "mobile_number",
    "mobile_number": "0812223333",
    "amount": "50000"
  }'
```

## Payout status

A payout has one of five statuses:

| Status | Meaning |
| :--- | :--- |
| `PENDING` | Reservepay accepted the payout and hasn't sent it to the bank yet. |
| `SENT` | The payout is with the bank. |
| `SUCCESSFUL` | The payout was paid to the recipient. |
| `FAILED` | The bank rejected the payout. |
| `CANCELLED` | The payout was canceled before it reached the bank. |

The `payout_completed` webhook fires for both `SUCCESSFUL` and `FAILED`, so read the `status` in the payload before you mark a payout as paid. To check one payout, call `merchants/find-payout` with the payout ID or your `external_id`. To find every failed payout, call `merchants/filter-payouts` with `status` set to `FAILED`.

## Limits and timing

Each payout must fall within the amount limits set for your merchant account and payout method. A payout outside them returns `INVALID_AMOUNT`. Your Reservepay account manager can tell you your limits and the bank processing schedule.

A successful API response means Reservepay accepted the payout, not that the recipient has the money. Wait for `payout_completed` or check `merchants/find-payout`.

## Payout fees

The recipient gets the full amount you send. The payout fee is deducted from your balance separately, and it appears in the payout's `fees` array and on your daily statement. See [Fees](/guides/reconciliation#fees).

## Error handling

When sending funds, you should be prepared to handle common errors:

- `INSUFFICIENT_BALANCE`: Your merchant account doesn't have enough funds for the requested payout.
- `INVALID_MOBILE_NUMBER` / `INVALID_NATIONAL_ID`: The PromptPay details provided are incorrect.
- `NOT_FOUND`: The specified contact or bank account could not be found.
- `INVALID_AMOUNT`: The payout exceeds the limits configured for your merchant account or the selected method.