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

```ts
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

| Action | When to use | Result |
| :--- | :--- | :--- |
| **Refund** | After capture/settlement | Funds are returned to the customer's account. |
| **Void** | Before settlement | The transaction is cancelled before funds move. |
| **Reverse** | After authorization, before capture | The hold on the customer's funds is released. |