Create optimal tax refund experiences for your customers by following these integration best practices. These best practices need to be implemented not only between the server and Alipay sides, but also between the terminals.

Alipay interfaces

We suggest integrating at least the tax refund, query and user information query interfaces. Follow these guidelines to use Alipay interfaces effectively.

Refund interface

When sending the refund request, take note of these actions:

• Ensure that out_order_no is unique in the system. Each different number issues a new refund transaction.
• Check and ensure that the value of identify_account_type and identify_account_no is correct.

After calling a refund interface, the following refund results might be returned from Alipay:

• If the value of code is 10000 and the value of msg is Success, it indicates that the transaction is successful and the money is refunded successfully. Record the returned Alipay tax number as reference.
• If the value of code is 20000, 20001 or 40006, use the same parameters to retry the refund request. The refund process can be retried for 3-10 times, with an interval of 3-10 seconds. If Alipay does not return any result after trying multiple times to refund, the merchant needs to use the query interface or contact the Alipay technical support team.
• If the value of code is 40001 or 40002, double check if the inputted parameters are correct, and use the query interface to check if the refund failed. If the refund has failed, try requesting a new refund with new parameters.
• If the value of code is 40004, refer to the error code in the refund interface for the corresponding action. In general, you will be required to use the query interface to retry.

If Alipay does not return any result, take the following action:

• If Alipay does not return any result due to network issues, the merchant needs to use the same parameters to retry the refund request. The refund process can be retried for 3-10 times, with an interval of 3-10 seconds. If Alipay does not return any result after trying multiple times to refund, the merchant needs to contact the Alipay technical support team.

Query interface

After calling a query interface, the following query results might be returned from Alipay:

• If the value of code is code is 10000 and the value of msg is Success, it indicates that the query is successful. Check the returned value of Status for further action.

• If the value of status is S, the refund is successful.
• If the value of status is F, the refund has failed.

• If the value of code is code is 40004, refer to the error code in the query interface for the corresponding action.

• ILLEGAL_ARGUMENT: Update the parameter and issue a new refund.
• TAX_REFUND_RESULT_UNKNOWN: Retry the same refund request 3-10 times with an interval of 5-10 seconds.
• SYSTEM_ERROR: Retry the same query request 3-10 times with an interval of 3-5 seconds. If Alipay does not return any result after trying multiple times to query, please contact Alipay Technical Support.

User information query interface

In Alipay FX refund, the customer can refund with the barcode generated by the user's Alipay app. The tax refund partner can scan the barcode to issue an instant refund at the airport. We may obtain the customer's Alipay user ID in advance in the following tax refund scenarios:

• For advance approval, the customer registers and submits the tax refund application.
• For batch refund later, the custom records the customer's information.

There are two ways to obtain the customer's Alipay user ID with this interface:

• The tax refund partner needs to prepare the device to scan the barcode or QR code that is generated by the user's Alipay app. In this mode, if iILLEGAL_IDENTIFY_ACCOUNT_NO is returned, request for the user to refresh the Alipay barcode and retry with the new barcode.
• The user's Alipay login account can be filled by the customer either offline or online. In this mode, we may need to confirm whether the customer has provided the correct account name.

• In the online mode of Alipay mini program, third-party app, or website, the tax refund partner can get the Alipay user ID via the authorization token.
• To confirm if the customer is eligible for tax refund, check that the value of eligible is true.
• If SYSTEM_ERROR is returned, please retry the same request 3-10 times with an interval of 3-5 seconds.