Obtain payment results
After calling the pay API, the Acquiring Service Provider (ACQP) can get the payment result in the following three ways:
- Get the payment result from the asynchronous payment notification sent by Alipay+ through the notifyPayment API.
- Call the inquiryPayment API to inquire about the payment result.
- Get the payment result from the synchronous response of the pay API. Note that generally the payment result returned by the pay API is
Uwhich means the payment is in processing. However, in some cases, such as when order validation fails,
The following diagram illustrates all the possible combinations of the results that you (the ACQP) might encounter in the three ways.
Figure 1. Possible combinations of the results
Payment results obtained by the three methods might be inconsistent. This is because the payment result returned by the response of the pay API and the inquiryPayment API might be in the intermediate status (unknown). To get the final status of the payment result, you need to keep retrying the inquiryPayment API call while waiting for Alipay+ to send the notifyPayment request. For how to handle the payment results that are returned by these two APIs, refer to the following section Collaboration between inquiryPayment and notifyPayment.
Collaboration between inquiryPayment and notifyPayment
Figure 2. Collaboration between the inquiryPayment API and notifyPayment API
It is recommended that the you take the following steps to ensure efficient collaboration between these two APIs:
- Create at least a table that includes the order number and order status in your local database.
- Set the initial order status to
- Depending on via which API the payment result is obtained, different actions are taken:
- If you receive the payment result (which is specified in the paymentResult parameter) from Alipay+ via the notifyPayment API, check if the order status is
INIT. If so, update the order status in your database; otherwise, you don't need to update the order status.
- If you obtain the payment result (which is specified in the paymentResult parameter) by calling the inquiryPayment API, depending on the value of the paymentResult.resultValue parameter, different actions are taken:
- If the value is
F, update the order status in your database.
- If the value is
U, retry to call the inquiryPayment API until the value becomes
F. Then update the order status in your database.
It is required that you support both notifyPayment API and inquiryPayment API so that you are guaranteed to obtain the final payment result. For example, when you cannot receive the payment result notification due to network or system problems, the inquiryPayment API can work as a complement to ensure you get the final (success or failure) payment result.
For how to receive payment notification through the notifyPayment API, see Receive payment notification.
For how to use the inquiryPayment API to inquire about the payment result, see Inquire about payment result.