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 account query, account confirm, tax refund apply and tax refund status query interfaces in order for CNY tax refunds to run smoothly. Follow these guidelines to use Alipay interfaces effectively.

Account query interface

After calling an account query interface, Alipay will return the following query results, and the partner needs to confirm it:

• is_success:  

• T: succeeded
• F: failed

This field indicates whether the request is successful. A successful request indicates that Alipay has received the request. This does not indicate that the tax refund has been successfully processed.

• alipay_user_id: An account opened for an Alipay user. When multiple user accounts are returned, the user needs to confirm and select one account to receive tax refund money from the partner.
• alipay_user_risk_status: Alipay account risk status, which indicates that the user's account is real-name authenticated and is safe to receive tax refund money.

Account confirm interface

This interface is used for urban refunds and airport kiosk refunds. After calling an account confirm interface, Alipay will return the following results, and the partner needs to confirm it:

• is_success:  

• T: succeeded
• F: failed

This field indicates whether the request is successful. A successful request indicates that Alipay has received the request. This does not indicate that the tax refund has been successfully processed.

• alipay_user_id: An account opened for an Alipay user to receive tax refund money from the partner.

If Alipay does not return any result due to network issues, the partner needs to use the same parameter to retry at least three times.

Tax refund apply interface

The partner system calls the interface for a single tax refund of a user to Alipay in real time, including the user's sales and tax refund information.

• is_success:  

• T: succeeded
• F: failed

This field indicates whether the request is successful. A successful request indicates that Alipay has received the request. This does not indicate that the tax refund has been successfully processed. If Alipay does not return any asynchronous notification or refund result, the partner needs to retry the account confirm interface.

Alipay sends the following key information in the notification, and the partner needs to confirm it:

• tax_refund_status: SUCCESS indicates that the tax refund is successful.
• doc_id
• out_order_no
• alipay_user_id

If no result, SYSTEM_ERROR, or UNKNOWN_EXCEPTION is returned, take the following action:

• The merchant needs to use the same parameters to retry the refund request. The refund process can be retried 3-10 times, with an interval of 3-10 seconds. If no result is obtained after multiple refund attempts, the merchant needs to contact Alipay Technical Support for help.

Tax refund status query interface

The partner system sends the query interface in the following cases:

• No asynchronous notification and refund result are returned from Alipay after the tax refund request.
• SYSTEM_ERROR or UNKNOWN_EXCEPTION is returned after the request.