Refunds

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 or through the UQPAY Dashboard.

Refund Processing

Follow these steps to process refunds:

Use the API or Dashboard to create a refund against a specific Payment Intent or Payment Attempt
You will be immediately informed that the refund request has been received and is being processed
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 API.

Sample Request

{
    "payment_intent_id": "PI1960644127393583104",
    "amount": "7.77",
    "reason": "Custom refund reason",
    "metadata": {
        "echo_test": "any value"
    }
}

Sample Response

{
    "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 API.