Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

Pay

After obtaining the buyer’s authorization, you can directly initiate the Auto Debit service without the need to go through the authorization process again for each payment.

To complete an Auto Debit payment, perform the following two steps:

  1. Initiate a payment
  2. Obtain the payment result

Step 1: Initiate a payment

If the balance of the target payment method is sufficient to pay for the buyer's order, you can call the pay API to initiate an Auto Debit payment. Pass in the following parameters correctly in the request:

  • productCode: Pass in the value AGREEMENT_PAYMENT.
  • paymentMethod.paymentMethodId: The value of the payment token (accessToken) that you obtain using the applyToken API.
  • paymentExpiryTime: You can only specify the parameter to limit the expiration time to less than 1 minute. The value of this field must comply with the ISO 8601 standard. If you do not specify a value for this field, the expiration time of an automatic deduction request is one minute after the payment request is sent. For details, see the pay API.
  • paymentNotifyUrl: The address used to receive asynchronous notifications. We recommend you pass in the parameter.

In the pay API response, learn whether the deduction is successful based on the result.resultStatus value:

  • If the value is S, the deduction is successful.
  • If the value is U, the transaction is still in progress. You need to inquire about the transaction status using the inquiryPayment API or wait for asynchronous notifications to obtain the transaction result.
  • If the value is F, the deduction fails. You need to handle it according to the result code.

If you cannot receive a response, we recommend you call the pay API with the same parameters.

Step 2: Obtain the payment result

Due to network issues, asynchronous notifications may not be sent or may be delayed. To obtain an accurate payment result, you must integrate both the asynchronous notifications and payment result inquiry service.

1. Receive asynchronous notifications

Apart from learning the payment result from the redirection to the payment result page, you can also set the asynchronous notification address by specifying paymentNotifyUrl in the pay API. When the payment is completed or expired, Antom sends an asynchronous notification to the address through the notifyPayment API.

When you receive the notification from Antom, you must return a response by following the code sample. If you do not return the response to Antom or the response is not received by Antom due to network issues, Antom automatically resends the asynchronous notification within 24 hours for up to eight times or until the correct response is received. The sending intervals are as follows: 0 sec, 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

Note: When a payment is successful, Antom immediately sends you an asynchronous notification of payment success. When a payment fails, Antom sends you an asynchronous notification of payment failure after the payment order is closed. The default order expiry time is 14 minutes after the payment is initiated.

2. Inquire about the payment status

We recommend that you inquire about the payment status by calling the inquiryPayment API. You can use the API after the payment request is initiated and before the order is closed.

In the response returned through the inquiryPayment API, paymentStatus indicates the payment status. See the following table for details:

paymentStatus

Type

Description

Handling

SUCCESS

Final status

The payment is successful.

You can display a payment success page.

PROCESSING

Intermediate status

The payment is being processed.

You can allow the buyer to continue to pay.

FAIL

Final status

The user has not paid or the payment fails.

You can allow the buyer to continue to pay or close the payment order.

CANCELLED

Final status

The payment is canceled by you.

You can allow the buyer to continue to pay or close the payment order.

Table 1. Details of paymentStatus

For details about the payment status, see Payment status description.

3. Best Practices

To obtain accurate payment results, we recommend that you maintain an order table in the database, which should include at least two fields: the order number and order status. And use the asynchronous notification and payment result inquiry services in the following way:

  • Asynchronous notification: Listen to Antom's asynchronous notifications and return a response upon receiving an asynchronous notification. Then check the order status in the database:
    • If the order status is INIT, update the order status according to the asynchronous notification.
    • If the order status is not INIT, it indicates that the final payment result has been obtained through the inquiry service and the order status has been updated accordingly. No further actions are needed.
  • Payment inquiry: Inquire about the payment status. Before each inquiry, you need to check the order status in the database:
    • If the order status is INIT, initiate an inquiry. Update the order status in the database if a final payment result is obtained, otherwise, continue the inquiry process.
    • If the order status is not INIT, it indicates that the inquiry process has been conducted and a final payment result has been obtained and used for updating the order status. No further actions are needed.

image

Figure 1. Best practice to use the asynchronous notification and payment result inquiry service