After processing a payment, mechants can perform post-payment actions such as inquiry, cancel, and refund. Go through the Development section to learn about how to invoke an API in both sandbox and production environments.

Query payment result

You can query the status of a transaction order by using the inquiryPayment API. Call the inquiryPayment API when one of the following cases is encountered:

• No clear result of the payment result can be obtained.
• The payment process times out and no payment result is obtained. 
• A refund record related to the transaction needs to be checked.

Use the same paymentRequestId used in the pay API to query the payment transaction status. After Antom processes the result, the payment or refund details are to be returned to the merchant synchronously. If no response from Antom is received, retry the inquiry process.

Construct the request message

Construct the request message with the HTTP body as below:

{
   "paymentRequestId": "pay_test_1106_0002"
}

Handle the response

Process the inquiry response by verifying the signature of the notification. The following example shows a typical response for an inquiry request:

{
    "result":{
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    },
    "paymentStatus": "Success",
    "paymentRequestId":"pay_test_1106_0002",
    "paymentId":"20190608114010800100188820200355883",
    "paymentAmount":{
        "value":"500",
        "currency":"USD"
    },
    "actualPaymentAmount":{
        "value":"500",
        "currency":"USD"
    },
    "paymentCreateTime":"2019-06-01T12:01:01+08:30",
    "paymentTime":"2019-06-01T12:01:01+08:30"
}

Note: Here are details about the result status that might be returned for a query request:

• S: indicates that the inquiry was successful and the merchant can get the payment status from the value of paymentStatus.
• F : a system alert will be triggered after getting a resultStatus of F. The merchant's technical support team must investigate the root cause. If the root cause is fixable and the order still exists in the Antom system, the merchant needs to retry the inquiryPayment API until a result of S is obtained.
• U: the merchant needs to call the inquiryPayment API with the same parameters multiple times after getting a resultStatus of U, until a result of S or F is obtained. After the maximum number of retries, if still no S or F is returned, the merchant must call the cancel API to cancel the transaction.

Cancel the transaction

You can cancel a transaction if the transaction encounters technical issues during making the payment. The cancel API can be used to roll back all the actions performed in the Antom system regarding the specific transaction. The cancellable period is specified in the contract. If being out of the agreed cancellable period, the cancellation cannot be performed. 

Use the same paymentId that is used in the pay API to cancel the payment transaction. After Antom processes the cancellation, the cancellation result is to be returned to the merchant synchronously. If no response from Antom is received, retry the cancellation process.

Construct the request message

Construct the request message with the HTTP body as below:

{
    "paymentId":"20190612184010800100188820200355884"
}

Handle the response

Process the cancellation response by verifying the signature of the notification. The following example shows a typical response for a cancellation request:

{
    "result": 
    {
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    },
    "paymentRequestId":"pay_2089760038715669_202775745075669",
    "paymentId":"20190612184010800100188820200355884",
    "cancelTime":"2019-06-12T19:07:11+08:00"
}

The following graphic shows the process of canceling the transaction:

Figure 1. Cancellation process

Notes:

1. Integrator might implement the store and forward logic in the gateway. If the cancel request reaches to gateway before the pay API request, the cancel request should not be relayed to the next hop. 
2. Here are details about the result status that might be returned for a cancellation request:

• S: indicates that the cancellation was successful.
• F : a system alert will be triggered after getting a resultStatus of F. The merchant's technical support team must investigate the root cause. If the root cause is fixable and the order still exists in the Antom system, the merchant needs to retry the cancel API until a result of S is obtained.
• U: the merchant needs to call the cancel API with the same parameters multiple times after getting a resultStatus of U, until a result of S or F is obtained. After the maximum number of retries, if still no S or F is returned, the system alarm is to be triggered and the merchant's technical support team needs to be involved to solve the problem.

Refund

You can issue a refund by using the refund API. The refund service is only applicable to a transaction that has been successfully paid and can be initiated any time after the transaction being paid and before the refund period expiration.

The refund of a transaction can be full or partial, that is, the refund amount can be the same as or less than the original transaction amount that has been paid. If a refund request encounters a failure, retry for a reasonable number of times and follow these suggestions:

• Use the original refund request ID and retry the refund request. Antom supports idempotency if a merchant uses the same refund request.
• The maximum number for retires and the interval for synchronous and asynchronous refund should be configured. 

No fee is charged for a refund transaction. Your contract with Antom determines whether the transaction fee charged by Antom will be refunded or not. After Antom processes a refund request, the refund is settled by transferring funds to payer's funding instrument. It depends on a bank's policy to determine when a refund settlement can finish. If a payer makes a payment with a credit card and rejects to pay for the credit card's balance, the rejected amount cannot be refunded.

Construct the request message

Construct the request message with the HTTP body as below:

{
 "paymentId":"201811291907410100070000001111",
 "refundRequestId":"201811291907410200070000001111",
 "refundAmount":{
    "value":"100",
    "currency":"USD"
 }
}

Handle the response

Process the cancellation response by verifying the signature of the notification. The following example shows a typical response for a refund request:

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
 "refundAmount":{
    "value":"100",
    "currency":"USD"
 },
 "refundTime": "2020-10-10T12:01:01+08:30",
 "paymentId":"201811291907410100070000001111",
 "refundRequestId":"201811291907410200070000001111",
 "refundId":"401811291907410200070000001111"
}

The following graphic shows the process of using a refund service:

Figure 2. Refund process

Notes:

1. After Antom completes a refund, the transaction cannot be canceled.
2. Integrator might implement the store and forward logic in the gateway. If the refund request reaches to gateway before the gateway getting the success payment result, the refund request should not be relayed to the next hop.
3. Here are details about the result status that might be returned for a refund request. The merchant must get a confirmative result status, either S or F for a refund request:  

• S: indicates that the refund was successful.
• F: indicates that a system alert will be triggered after getting a resultStatus of F. The merchant's technical support team must investigate the root cause. If the root cause is fixable and the order still exists in the Antom system, the merchant needs to retry the refund API one more time.
• U: the merchant needs to call the refund API multiple times until a result of S or F is obtained. After the maximum number of retries, if still no S or F is obtained, the merchant should initialize an asynchronous refund request. After retrying the maximum number of async refund request, system alarm should be triggered and the merchant's technical support team needs to be involved to solve the problem.

Inquire about the refund status

A merchant can obtain a refund result in two ways: wait for the refund API's response or actively call the inquiryRefund API.

For the following situations, call the inquiryRefund API to get a refund result:

• No clear refund result is obtained for a timeout.
• A user requests a refund result from the merchant.

If the domain name is open-na.alipay.com, the request URLs for the inquiryRefund API are as follows:

• Sandbox environment: https://open-na-global.alipay.com/ams/sandbox/api/v1/payments/inquiryRefund
• Production environment: https://open-na-global.alipay.com/ams/api/v1/payments/inquiryRefund

As a merchant, you can use refundId or refundRequestId to initiate the inquiryRefund request.

If the refund times out and refundId cannot be obtained, you can only use the refundRequestId field to send the inquiryRefund request.

If refundId is obtained, it is recommended to use the refundId field.

Note that if both refundId and refundRequestId are specified, refundId takes precedence.

The following example shows an inquiryRefund request with the refundId field specified.

{     "refundId": "2021080419401080130018866020092XXXX" }

The following example shows a response to an inquiryRefund request. The refund result is presented in the refundStatus field.

{
    "refundAmount": {
        "currency": "HKD",
        "value": "10000"
    },
    "refundId": "2021080419401080130018866020092XXXX",
    "refundRequestId": "amsdemorefund_zhangsan_zs_20210804_165236_XXX",
    "refundStatus": "SUCCESS",
    "refundTime": "2021-08-04T01:52:37-07:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

• refundId: The unique refund processing ID. To implement the same refund polling, this field must be unique. To implement different refunds polling, this field must be different.
• refundRequestId: The unique ID assigned by a merchant to identify a refund request.
• refundStatus: This field indicates the refund result of the order. This field is returned when the value of result.resultStatus is S or the refund record can be found. The value of this field can be:

• SUCCESS: This value indicates the refund succeeds.
• PROCESSING: This value indicates that the refund is still processing. When this value is returned, the merchant can retry the refund API.

• result: This field only indicates the calling status of this inquiry request. It does not indicate the refund status.

Details about the result status that might be returned for a refund inquiry request are as follows:

• S: indicates that the inquiryRefund API successfully and the merchant can get the payment status from the value of refundStatus.
• F: indicates that the inquiryRefund API was failed to be called, which might be caused by system error or invalid parameters.
• U: indicates that the calling status of the inquiryRefund API is unknown. Use the same request parameters to retry the inquiry request.

For more information about when to implement the inquiryPayment, cancel, and refund APIs, see Best practice.

More information

Alipay Developer Center user guide

Test