refund
Use this API to initiate a synchronous or asynchronous refund for a successful payment.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：
Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
- If the data type of a field is Integer and its value is 20, set it as "20".
- If the data type of a field is Boolean and its value is true, set it as "true".
Request parameters
refundRequestId String REQUIRED
The unique ID assigned by the merchant to identify a refund request.
More information:
- This field is an API idempotency field.The merchant uses the refundRequestId field for idempotency control. For payment requests that are initiated with the same value of refundRequestId and reach a final status (S or F), the same result is to be returned for the request.
- Maximum length: 64 characters
paymentId String REQUIRED
The unique ID assigned by Antom for the original payment to be refunded.
More information:
- Maximum length: 64 characters
referenceRefundId String
The unique ID to identify a refund, which is assigned by the merchant that directly provides services or goods to the customer.
More information:
- Maximum length: 64 characters
refundAmount Amount REQUIRED
The refund amount that is initiated by the merchant.
refundReason String
The refund reason
More information:
- Maximum length: 256 characters
Response parameters
result Result REQUIRED
The request result contains information such as status and error codes.
refundRequestId String
The unique ID that is assigned by the merchant to identify a refund request.
More information:
- Maximum length: 64 characters
refundId String
The unique ID that is assigned by Antom to identify a refund. A one-to-one correspondence between refundId and refundRequestId exists.
More information:
- Maximum length: 64 characters
paymentId String
The unique ID assigned by Antom for the original payment to be refunded.
More information:
- Maximum length: 64 characters
refundAmount Amount
The refund amount collected by the payment executor for this refund.
refundTime Datetime
The date and time when the refund reaches a final state of success or failure.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
grossSettlementAmount Amount
The total settlement amount, which equals to the transaction amount multiplied by the value of settlementQuote.
Note: This field is empty when the settlement currency is the same as the transaction currency.
settlementQuote Quote
The exchange rate between the settlement currency and transaction currency at the time of transaction, which is provided only in the locked-in rate case.
Note: This field is empty when the settlement currency is the same as the transaction currency.
Request
Response
More information
This section gives additional information about the key parameter. See the following list for details:
- refundRequestId:
The refund can be full or partial. A transaction can have multiple refunds as long as the total refund amount is less than or equal to the original transaction amount. If being out of the refund window, the refund request will be declined. Use the same refundRequestId to retry a refund in case of timeout or when the returned resultStatus is U. - refundId:
The parameter can be used for the refund inquiry.
Result process logic
For different request results, different actions are to be performed. See the following list for details:
- If the value of result.resultStatus is
S, for synchronous refund, the refund succeeds. For an asynchronous refund, the refund request is processed successfully and the merchant can call the inquiryPayment interface to query the refund result. - If the value of result.resultStatus is
F, the refund fails. Usually, the failure is caused by a refund initiated outside the refund window (result. resultCode= FREFUND_WINDOW_EXCEED). If the refund still needs to be processed, manual intervention is needed. - If the value of result.resultStatus is
U, the result is unknown. Processing failure might occur due to system or network issues. The merchant can retry with the same refundRequestId.
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | The refund is successful, no further action is needed. |
| ACCESS_DENIED | F | Access is denied. | Contact Antom Technical Support for detailed reasons. |
| CLIENT_INVALID | F | The client is invalid. | Check whether clientId is correct. |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Use the currency that is agreed in the contract. |
| MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. | Check whether the media type is correct. |
| MULTIPLE_REFUNDS_NOT_SUPPORTED | F | Multiple refunds are not supported. | Check whether multiple refunds exist. |
| MERCHANT_BALANCE_NOT_ENOUGH | F | The merchant balance is not enough. | Call the interface again after the merchant has sufficient balance. The refundRequestId field needs to be changed when you try again. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. | Check whether the HTTP method is correct. |
| ORDER_IS_CANCELED | F | The transaction is canceled. | You cannot refund the transaction because it is canceled. |
| ORDER_NOT_EXIST | F | The order does not exist. | Check whether paymentId is correct. |
| ORDER_STATUS_INVALID | F | The order status is invalid. | Check the order status. |
| REFUND_AMOUNT_EXCEED | F | The total refund amount exceeds the payment amount. | Confirm whether the total refund amount exceeds the payment amount. |
| REFUND_WINDOW_EXCEED | F | The refund date exceeds the refundable period that is agreed in the contract. | Confirm whether the refund date exceeds the refundable period. |
| REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | Use a unique refundRequestId to initiate the payment again. |