API references
Search documentation... ⌘K
API references
Open merchant dashboard
Merchant API
All our references

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
This endpoint requires an API key. Read our authentication guide for more information.
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
New to Reservepay? Read our guide on how to call endpoints to get started.
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. 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). If no country prefix is provided, it is inferred from the provider's country.

national_id string

Optional. The recipient's national ID (exactly 13 digits) for PromptPay payouts. Required when payout_method is national_id.

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.

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

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.

CODE SAMPLES
curl
Learn how to run these code samples in your terminal by reading our guide.