Create optimal payment experiences for your customers by following these best practices for integrations. 

The Payment Result Inquiry interface can be used to check the transaction status of a payment request retry process. You can decide further actions based on the result of the inquiry process. The Inquiry interface can be used for the following cases:

Use case 1

If a payment API is called and a successful payment result is returned, the merchant can use the paymentId or paymentRequestId field to inquire the payment result of the payment request by calling the Inquiry interface.

Figure 1. Initiate a query process for a successful payment

Use case 2

If a payment API is called and a timeout payment result or a payment result with unknown exception is returned, the merchant can use the paymentRequestId field to inquire the payment result of the payment request by calling the Inquiry interface.

Figure 2. Initiate a query process for a payment that times out or with unknown result 

Use case 3

If a cancel API is called and a timeout result or a result with unknown exception is returned, the merchant can use the paymentId or paymentRequestId field of the original payment request to query the cancel result.

Figure 3. Initiate a query process for a cancellation process that times out or with unknown result 

Use case 4

If a capture API is called and a timeout result or a result with unknown exception is returned, the merchant can use the paymentId or paymentRequestId field of the original payment request to query the capture result.

Note:

Using the captureRequestId field for the query process is not supported.

Figure 4. Initiate a query process for a capture process that times out or with unknown result 

Use case 5

If a refund API is called and a timeout result or a result with unknown exception is returned, the merchant can use the paymentId or paymentRequestId field of the original payment to query the refund result.

Note:

Using the refundRequestId field for the query process is not supported.

Figure 5. Initiate a query process for a refund process that times out or with unknown result 

You need to choose between a retry and an inquiry process when handling exceptions or handling the payment process.

Handling exceptions

For a timeout process or a process that receives an unknown exception, a retry process performs the action again if the action is not completed while an inquiry process does not perform the action again. If the action is already completed, the retry process and the inquiry process return the same result that shows the status of the corresponding process.

If you want to make a payment request or a refund request be completed regardless of the payment or refund result, it is recommended to initiate a retry process when a timeout or unknown exception is received.

Handling the payment in process

When an auto debit payment is in process, the system is waiting for the downstream nodes to complete the payment. You can initiated an inquiry process to inquire the transaction status until it is completed, or you can initiate a retry process instead.

When a cashier payment is in process, the system is waiting for a wallet user to be redirected to the cashier page to complete the payment. Before the payment process is completed and reaches a final status of success or failure, the retry or inquiry process returns a result that shows the payment is in process. Only when the payment process is completed, the retry or inquiry process returns the final status of the payment process, which is success or failure.

Note:

For a cashier payment, if and only if the payment is in process, the redirection action form and other related information are still to be included so that the user can be redirected again if needed.

If you want to use the inquiry or retry process to get the status of the previous payment call, it is recommended to use an exponential backoff strategy when retrying or calling the Payment Inquiry interface to avoid flooding the API and running into rate-limiting.

Only cashier payments get the payment notification that shows the final status of a payment in real-time after the completion of user's payment action on the cashier page. 

The following table shows the list of notifications for different cashier payment cases:

Table 1. The list of notifications for different cashier payment cases

Currency related data fields exist for both APIs and reconciliation reports. One of them is the payment amount that is presented by the amount field. The amount field has sub fields of currency and value. And all currency fields of Alipay APIs or reports follow the same definition. 

Table 2. Subfields of the amount field

Notes:

• The wallet is specified by the value of paymentMethodType, and the corresponding currency for the wallet is specified by currency.
• The actual value in the value field of the amount field is represented in the smallest unit of the currency. Alipay follows the ISO 4217 standard for the definition of the smallest unit of a currency. For example:

Table 3. Details about the currency

The minimum payment or refund amount differs for each wallet. The following table shows the details of the minimum payment or refund amount of each wallet.

Table 4. The minimum payment or refund amount for different wallet.