Refund
Discover Antom's refund rules and learn how to initiate a refund for a successful transaction.
Refund rules
The following are the relevant refund rules:
- Commission fee: Whether the commission fee is returned is subject to the contract.
- Refund exchange rate:
- For cross-currency settlements with locked-in currency conversion, the exchange rate on the day the refund is issued is applied.
- For cross-currency settlements with non-locked-in currency conversion, the exchange rate on the following day the refund is issued is applied.
- No exchange rate is involved when the settlement currency is the same as the transaction currency.
- Partial refund: Whether a partial refund is allowed depends on the payment method that the buyer used for a payment. For details, see Refund capabilities of payment methods.
- Refund period: The refund period depends on the payment method that the buyer used for payment. For details, see Refund capabilities of payment methods.
- Refund processing time: The refund processing time may vary for different payment methods. Contact Antom technical support for more details.
Refund methods
After the transaction is paid successfully, you can issue a refund by using the refund API or Antom Merchant Portal.
Refund using the refund API
The refund process through the refund API varies depending on the payment method and may proceed either synchronously or asynchronously:
- Synchronous refund: After calling the refund API, the response directly indicates whether the refund was successful or failed. Nevertheless, there is a slight possibility of system exceptions or payment channel processing exceptions, which might result in different responses.
- Asynchronous refund: After calling the refund API, a response indicates the refund is in process. You are then required to periodically check the refund status or wait for a notification that will provide the final refund status.
The following table shows payment methods supported by the synchronous and asynchronous refunds.
Synchronous refund | Asynchronous refund |
Alipay+ payment methods | All other payment methods default to asynchronous refunds. For a comprehensive list of payment methods, refer to Payment methods. |
Mastercard and Visa cards through acquirers 2C2P HK and 2C2P SG |
The following table shows API compatibility with synchronous and asynchronous refund processes.
API | Synchronous refund | Asynchronous refund |
Supported | Supported | |
Not supported | Supported | |
Supported | Supported |
Table 1. API capabilities supported by synchronous and asynchronous refund
Workflow
The following is the workflow for synchronous and asynchronous refunds.
Synchronous refund
Figure 1. Workflow of synchronous refund
Asynchronous refund
Figure 2. Workflow of asynchronous refund
Initiate a refund
When initiating a refund through the refund API, the key parameters in the request are listed as follows:
Parameter | Description |
refundRequestId | The unique identifier that you assign to a payment. |
paymentId | The unique identifier that Antom assigns to the original payment to be refunded. |
refundAmount | The refund amount must be no less than the minimum refund amount (which is usually the same as the minimum payment amount) and no greater than the refundable amount of a payment. |
refundNotifyUrl | The URL for receiving asynchronous refund notifications. |
Table 2. Key parameters of refund requests
The following requirements for a refund request must be satisfied when you use the refund API. Failure to meet these criteria will result in Antom issuing the respective error codes:
Refund requirement | Error code | |
Refund currency | The value of the parameter refundAmount.currency in the refund request needs to be consistent with the value of the parameter paymentAmount.currency used for initiating a payment through the pay API. |
|
Refund amount | The value of the parameter refundAmount.value in the refund request must be no less than the minimum refund amount (which is usually the same as the minimum payment amount) and no greater than the refundable payment amount. |
|
Payment status | For card payment methods:
For other payment methods, the refund is allowed only when the value of the paymentStatus parameter of the original payment is |
|
Refund period | The refund is allowed only when the refund is issued within the refund period of the corresponding payment method. |
|
Table 3. Refund requirements
Obtain the refund result
Obtaining refund results varies between synchronous and asynchronous refund processes:
- Synchronous refund:
- Asynchronous refund:
Check the refund status through the refund API
After you call the refund API, Antom synchronously returns the refund result. The resultStatus parameter in the API response indicates the refund status of this payment. The values of resultStatus are explained as follows:
resultStatus | Explanation |
| The refund is successful. |
| The refund failed. See the error codes of the refund API for troubleshooting. |
| The refund is being processed. For synchronous refunds, the following scenarios may occur:
For asynchronous refunds, if the value of resultCode is |
Table 4. Values of resultStatus
Inquire about the refund status
Regardless of the payment method used for a payment, you can call the inquiryRefund API to inquire about the refund status. The refund status is indicated by the refundStatus parameter in the response. The following table explains the possible values of the refundStatus parameter:
refundStatus | Explanation |
| The refund is successful. |
| The refund failed. |
| The refund is being processed. |
Table 5. Values of refundStatus in the inquiryRefund API
Receive an asynchronous notification of the refund status
Before you can receive an asynchronous notification of the refund status, you must set a notification address. You can configure the address in Antom Dashboard or by specifying the refundNotifyUrl parameter in the refund API.
Only in the case of asynchronous refunds will Antom send you a refund notification through the notifyRefund API. After you receive the notification, check the refund status through the refundStatus parameter in the notification. The values of refundStatus are explained as follows:
refundStatus | Explanation |
| The refund is successful. |
| The refund failed. |
Table 6. Values of refundStatus in the notifyRefund API
Inquire about the refund records
You can view the refund records of a transaction by using the inquiryRefund API. If a transaction has been refunded, the parameter transactions shows the refund records of the transaction.
Refund in Antom Merchant Portal
You can issue a refund on Antom Merchant Portal. For more information about how to issue a refund and view the refund result, see Refund transactions on Antom Merchant Portal.