Sending funds

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 get-balance, which returns the amount you can send right now. To see funds that are still on hold, see 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 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.

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 send-payout-to-contact. The recipient must already be a contact. Create one with add-contact (see 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

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:

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 find-payout with the payout ID or your external_id. To find every failed payout, call 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 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.

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.