Refunds
After a successful payment, your server can request a refund through Create or cancel a 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 and Request signing.
Request a refund and handle the result
Submit the refund request
Call Create or cancel a 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: identified by
txnType=REFUND. Use the refund'stransactionIdandstatusto update the corresponding refund record. - Refund request rejection webhook: identified by
notifyType=REFUND_AUDIT. Sent only when Onerway rejects the refund request during review.
Follow 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.
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. 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.
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 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.
originTransactionId identifies the original payment. When cancelling a refund request, the same field identifies the refund transaction. These operations use different transaction IDs.