# Refund Payment


> Start a refund and track its status.

Canonical: https://docs.chiwapay.com/payment-refund

`POST /payments/:id/refund`

Starts a refund for a transaction that is already `paid` and has not entered settlement.
The ShopeePay Partner SDK does not support refunds; this endpoint applies to GoPay transactions only.
When the request succeeds, the transaction status changes to `refund_processing`.

## Status Rules

| Initial status | Result |
| --- | --- |
| `paid` | `refund_processing` |
| `created`, `pending`, `expired`, `failed`, `cancelled`, `settled`, `refund_processing`, `refund_failed`, `refunded` | Cannot be refunded. |

## Refund Calculation

The main refund amount is the customer-paid amount (`total_amount`).
The customer receives that amount in full. The merchant settlement balance is still reduced by `fee_amount` as the transaction service fee.

| Fee payer | Customer pays | Main refund amount | Notes |
| --- | --- | --- | --- |
| `buyer` | `amount + fee_amount` | `amount + fee_amount` | The customer-paid amount is refunded through the provider; `fee_amount` still reduces merchant settlement. |
| `merchant` | `amount` | `amount` | `fee_amount` remains the merchant fee and reduces settlement. |

## Path Params

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Transaction UUID or `reference_id`. |

## Request Example

```tsx
<ApiExample method="POST" path="/payments/f2b1d5b0-7b1f-4c5d-9c37-93f0c8f6a001/refund" />
```

## Response

```json
{
  "payment": {
    "id": "f2b1d5b0-7b1f-4c5d-9c37-93f0c8f6a001",
    "reference_id": "PAY-LXAMPLE",
    "merchant_reference_id": "ORDER-1024",
    "payment_method_code": "qris",
    "currency": "IDR",
    "amount": 150000,
    "fee_amount": 1050,
    "net_amount": 150000,
    "total_amount": 151050,
    "status": "refund_processing"
  }
}
```

## HTTP Error Code

| HTTP | Code | Description |
| --- | --- | --- |
| `400` | `payment_refund_failed` | Transaction cannot be refunded from its current status. |
| `401` | `invalid_api_key` | Secret key is invalid. |
| `403` | `merchant_not_approved` | Merchant is not active. |
| `404` | `not_found` | Transaction was not found. |