> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds

> Process refunds to return funds to customers when they return goods or services.

## Overview

When a customer wishes to return goods or services, you can use the refund operation to return funds. It's important to process refunds promptly to avoid disputes raised by customers with their banks.

## Refund Service Information

The following table introduces more information about the refund service provided by UQPAY:

| **Item**                     | **Details**                                                                                                                                                                                                                                                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Refund expiration period** | UQPAY does not impose time restrictions on merchants for refund requests. Merchants can initiate refunds at any time, as long as the order status allows refunds. The final success of the refund depends on the channel's refund expiration period, and UQPAY will directly pass through the channel's processing results. |
| **Refund eligibility**       | Refunds are only allowed when the Payment Intent’s `intent_status` is `SUCCEEDED`.                                                                                                                                                                                                                                          |
| **Refundable amount**        | UQPAY supports full refunds, partial refunds, and multiple partial refunds. For a single transaction, the total amount of multiple partial refunds cannot exceed the original amount paid by the user.                                                                                                                      |
| **Fee items**                | Will be specified in the commercial agreement.                                                                                                                                                                                                                                                                              |
| **Refund methods**           | You can refund payments through the [Create a refund API](/global-acquiring/v1.6/api-reference/create-refund) or through the UQPAY Dashboard.                                                                                                                                                                               |

## Refund Processing

Follow these steps to process refunds:

1. Use the [API](/global-acquiring/v1.6/api-reference/create-refund) or Dashboard to create a refund against a specific Payment Intent or Payment Attempt
2. You will be immediately informed that the refund request has been received and is being processed
3. You will be notified when the refund succeeds through webhook

## Refund Statuses

Based on UQPAY's payment system design, refunds have the following statuses:

| Status       | Description                   | Phase         | Webhook Event                |
| ------------ | ----------------------------- | ------------- | ---------------------------- |
| `INITIATED`  | Refund has been initiated     | Initial state | `acquiring.refund.created`   |
| `PROCESSING` | Refund is being processed     | Processing    | -                            |
| `SUCCEEDED`  | Refund completed successfully | Final state   | `acquiring.refund.succeeded` |
| `FAILED`     | Refund failed                 | Final state   | `acquiring.refund.failed`    |

## How to refund a payment

### Refund payment via API

The following sample shows the request and response when you call the [Create a refund](/global-acquiring/v1.6/api-reference/create-refund) API.

#### Sample Request

```json theme={null}
{
    "payment_intent_id": "PI1960644127393583104",
    "amount": "7.77",
    "reason": "Custom refund reason",
    "metadata": {
        "echo_test": "any value"
    }
}
```

#### Sample Response

```json theme={null}
{
    "amount": "7.77",
    "create_time": "2025-08-27T18:06:40+08:00",
    "currency": "SGD",
    "metadata": {
        "echo_test": "any value"
    },
    "payment_attempt_id": "PA1960644127573938176",
    "payment_refund_id": "RF1960645128594919424",
    "reason": "Custom refund reason",
    "refund_status": "INITIATED",
    "update_time": "2025-08-27T18:06:40+08:00"
}
```

You can determine whether the refund has been successfully processed either by listening to the `acquiring.refund.succeeded` webhook, or by actively querying the `refund_status` via the [**Retrieve a refund**](/global-acquiring/v1.6/api-reference/retrieve-refund) API.

### Refund payment via Dashboard

!\[\[Pasted image 20250828140526.png]]