# Refunds

> Refund a payment and query a refund. Card refunds are full refunds, and are reviewed before they complete.

## Create Refund

`POST /api/v1/refunds/create`

### Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `original_order_no` | string | One of two | HansaPay original order number |
| `original_merchant_order_no` | string | One of two | Merchant original order number |
| `merchant_refund_no` | string | Yes | Merchant refund order number, max 64 characters |
| `refund_amount` | string | Yes | Refund amount, in the original order's currency |
| `reason` | string | No | Refund reason |
| `notify_url` | string | No | Refund notification URL. If omitted, no refund notification is sent |
| `metadata` | string | No | Merchant passthrough field, returned in the refund notification |

Notes:

- Card, Apple Pay and Google Pay payments support one refund of the full amount only. A partial amount is rejected with `This payment channel does not support partial refunds; only full refunds are allowed`
- These refunds start as `PENDING` and are reviewed before they complete; HansaPay checks them every few minutes and sends `refund.updated` when they finish. A refund the provider has no record of after 30 minutes becomes `FAILED`
- Cash App refunds can be partial. They start as `PENDING` and complete once the provider confirms them, usually within a few minutes; HansaPay sends `refund.updated` when they do
- The refund amount and the refund fee are held from your available balance while the refund is pending, and released if it fails. If the balance does not cover them, the refund is rejected
- A rejected refund still uses up its `merchant_refund_no`; the refused refund is recorded as `FAILED`
- Refund statuses: `PENDING` / `SUCCESS` / `FAILED`

### Successful `data`

| Field | Type | Description |
| --- | --- | --- |
| `refund_no` | string | HansaPay refund number |
| `merchant_refund_no` | string | Merchant refund number |
| `original_order_no` | string | Original HansaPay order number |
| `original_merchant_order_no` | string | Original merchant order number |
| `status` | string | Refund status |
| `refund_amount` | object | Refund amount |
| `created_at` | string | Creation time |

### Full success response example

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "refund_no": "R202406240001",
    "merchant_refund_no": "MR202406240001",
    "original_order_no": "O202406240001",
    "original_merchant_order_no": "M202406240001",
    "status": "PENDING",
    "refund_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "created_at": "2026-06-24T11:00:00+08:00"
  }
}
```

## Query Refund

`POST /api/v1/refunds/query`

### Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refund_no` | string | One of two | HansaPay refund number |
| `merchant_refund_no` | string | One of two | Merchant refund number |

### Successful `data`

| Field | Type | Description |
| --- | --- | --- |
| `refund_no` | string | HansaPay refund number |
| `merchant_refund_no` | string | Merchant refund number |
| `original_order_no` | string | Original HansaPay order number |
| `original_merchant_order_no` | string | Original merchant order number |
| `status` | string | Refund status |
| `refund_amount` | object | Refund amount |
| `reason` | string | Refund reason |
| `created_at` | string | Creation time |
| `updated_at` | string | Update time |

### Full success response example

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "refund_no": "R202406240001",
    "merchant_refund_no": "MR202406240001",
    "original_order_no": "O202406240001",
    "original_merchant_order_no": "M202406240001",
    "status": "SUCCESS",
    "refund_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "reason": "customer requested",
    "created_at": "2026-06-24T11:00:00+08:00",
    "updated_at": "2026-06-24T11:00:05+08:00"
  }
}
```
