Refunds, voids, and reversals

Overview

Reservepay provides multiple ways to manage your transactions after they have been initiated. Depending on the state of the payment and your business needs, you can refund, void, or reverse a payment.

Before attempting any of these actions, you should check the payment's eligibility by calling the /merchants/find-payment endpoint. The payment object includes three boolean fields that indicate which actions are currently available:

• refundable: True if the payment can be refunded (captured and settled).
• voidable: True if the payment can be voided (authorized but not yet settled).
• reversible: True if the authorization can be reversed (authorized but not yet captured).

In some cases, even if these fields are true, the operation may still fail. This can happen due to acquiring bank cut-offs, internal business rules, or specific limitations of the payment method used. Always handle potential errors from these endpoints gracefully.

Refunds

Refunds are used to return funds to a customer for a payment that has already been captured and settled. You can perform both full and partial refunds.

Refunding a payment

To refund a payment, first verify that refundable is true. Then, use the /merchants/refund-payment endpoint. You must provide the payment_id of the transaction you wish to refund.

• Full refund: If you don't specify an amount, the full refundable amount will be returned to the customer.
• Partial refund: Specify an amount in the smallest currency unit (e.g., satang for THB) to refund a specific portion of the payment.

Example: Partial refund

await fetch('https://api.reservepay.com/merchants/refund-payment', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Api-Version': '2025-04-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_id: 'pay_1234567890',
    amount: 5000 // Refunds 50.00 THB
  })
})

Eligibility for refunds

A payment is eligible for a refund only if it has been captured and billed. If a payment is already fully refunded or the integration doesn't support refunds, you will receive a NOT_REFUNDABLE error.

Voids

Voids are used to cancel a payment that has been authorized but not yet settled. This is typically used when you want to cancel a transaction immediately after it was made, before any funds have actually moved.

Before voiding, ensure voidable is true. To void a payment, use the /merchants/void-payment endpoint with the payment_id.

Reversals

Reversals are used specifically for authorized payments that have not yet been captured. When you reverse an authorization, the hold on the customer's funds is released.

Before reversing, ensure reversible is true. To reverse an authorization, use the /merchants/reverse-payment endpoint with the payment_id.

Summary of differences