# Refunds

> Request a refund, handle refund results and request rejections, and query the outcome or cancel a request before approval.

After a successful payment, your server can request a refund through [Create or cancel a refund](/payments/api-reference/endpoints/create-or-cancel-refund). Use this API whether the original payment was created through Checkout, Web SDK, or Direct API.

## Before you begin

Refund availability, support for partial or multiple refunds, and the refund request time limit depend on the payment method. Most payment methods support partial and multiple refunds. The total refunded amount must not exceed the original payment amount, and refund amounts use the currency of the original transaction.

Save the original payment's Onerway `transactionId` and confirm that the payment succeeded. Before calling the API, complete [Setup](/payments/get-started/setup) and [Request signing](/payments/get-started/request-signing).

## Request a refund and handle the result

<steps level="3">

### Submit the refund request

Call [Create or cancel a refund](/payments/api-reference/endpoints/create-or-cancel-refund) with `refundType=0`, the original payment transaction ID in `originTransactionId`, and the amount to refund in `refundAmount`. See the API reference for all field requirements and a complete request example.

You can provide a merchant transaction number for this refund in `merchantTxnId` for tracking and reconciliation. Onerway generates it if omitted. Duplicate submissions are rejected.

### Save the refund transaction ID

`respCode=20000` means the refund request was accepted, not that the refund succeeded. Save the new refund transaction ID returned in `data` and link it to the original payment and your refund record. Use it to process notifications, query the refund, or cancel the request.

### Handle refund notifications

Refund notifications are sent to the `notifyUrl` from the original payment request. Your server needs to handle two notification types:

- [Refund result webhook](/payments/api-reference/webhooks/refund-result): identified by `txnType=REFUND`. Use the refund's `transactionId` and `status` to update the corresponding refund record.
- [Refund request rejection webhook](/payments/api-reference/webhooks/refund-audit-rejected): identified by `notifyType=REFUND_AUDIT`. Sent only when Onerway rejects the refund request during review.

Follow [Webhooks](/payments/get-started/webhooks) for signature verification, acknowledgement, and deduplication. Once a notification reports success (`S`) or failure (`F`), update your refund record. No confirming query is needed.

</steps>

## Query a refund when needed

Wait for a Webhook to receive the refund result; continuous polling is not required. When you need to check refund progress or reconcile records, call [Query refunds](/payments/api-reference/endpoints/query-refunds). To query a single refund, use its refund transaction ID in `transactionId`. To query refunds associated with the original payment, use the original payment transaction ID in `originTransactionId`.

If a query result differs from a notification, see [Handle differences between query results and Webhooks](/payments/get-started/webhooks#handle-differences-between-query-results-and-webhooks).

Most refunds are credited immediately. Other refunds can take up to 25 days.

## Cancel a refund request

Submit the cancellation before Onerway approves the refund request. After approval, Onerway submits the request to the payment channel or card issuer. A processing status alone does not mean that the request can still be cancelled.

Call [Create or cancel a refund](/payments/api-reference/endpoints/create-or-cancel-refund) with `refundType=1` and the **refund transaction ID** to cancel in `originTransactionId`. See the API reference for the other required fields and a complete example.

A successful cancellation does not trigger a notification. Handle the synchronous response: `data` in a successful response equals `originTransactionId` from the request. To check the record, query using that refund transaction ID.

<note>

When requesting a refund, `originTransactionId` identifies the original payment. When cancelling a refund request, the same field identifies the refund transaction. These operations use different transaction IDs.

</note>