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

You can get the access token by using authCode and refresh the access token by using refreshToken.

When authCode is used to retrieve accessToken via the Access Token Application interface, if the token is permanent, neither the expiration date nor refresh token is to be returned. If the token is not permanent, a refreshToken along with the expiration date for both tokens is to be returned.  By default the token expiration time is two years. 

The authCode can only be used once for security reason. After the accessToken is generated, the authCode becomes invalidated.

Before the accessToken expires, the merchant can use refreshToken to get a new accessToken via the Access Token Application interface without asking the user to perform the account binding process again.  

When the merchant requests to refresh the token by using the Access Token Application interface, a new accessToken along with new refreshToken will be returned with the new expiration date. When processing the request, the corresponding accessToken becomes invalidated.

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.

Note:

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 access token expiration time varies for different digital wallet. The following table shows the expiration time for some digital wallets.

Table 4. Details about the access token expiration time.

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 5. The minimum payment or refund amount for different wallet.