To improve integration efficiency and avoid payment disputes, please read the best practices to ensure that the system and all involved parties make integration according to the standard procedures.

Task flow and API interactions

In Auto Debit, the overall procedure involves the following roles:

• User: An individual or institution that uses the payment service.
• Merchant: A company or individual that trades in goods or services. This role is the "you" in the documentation.
• Alipay: Alipay provides the Auto Debit service.
• Alipay+ MPP: Alipay+ Mobile Payment Provider. In Auto Debit, an Alipay+ Mobile Payment Provider is a digital wallet, such as GCash.

All APIs need to be used properly at the right time so that your system will perform as expected:

• For the authorization phase, it is suggested to create a data table that contains data about accessTokens created for each account. When the accessToken needs to be refreshed or invalidated, the table will be updated accordingly.
• For the payment and refund phase, it is suggested to create a table that contains data about the transaction. The table will be updated accordingly when the payment or refund action proceeds.

Figure 1. Overall procedure of Auto Debit integration

Obtain user authorization

You need to obtain the user's authorization before you can deduct money from the user's account automatically. To get the user's authorization, the following tasks need to be completed:

1. Configure your address to receive the authorization result notification.
2. Call the consult API to get authUrl and redirect the user to authUrl.
3. Get authCode after the user agrees to authorize.
4. Get accessToken by calling the applyToken API with authCode.
5. (Optional) Refresh accessToken by calling the applyToken API with the corresponding refreshToken when the accessToken is about to expire.
6. (Optional) Revoke the authorization by invalidating accessToken via the revoke API if you need.

In the preceding steps, authUrl and authCode can be used only once. If the authorization process fails, call the consult API again with an updated value for the authState field in the request. For example, the updated value for the authState field can be made by appending numbers at the end of the previous value, such as authstatexxxx_1. In addition, to ensure a smooth client-side redirection process, follow the integration instructions in Redirect from merchant to wallet and Redirect form wallet to merchant.

If the accessToken is about to expire, you can use the applyToken API with the correct fields specified to refresh the accessToken. In addition, you can use the revoke API to invalidate the accessToken when necessary.

The following graphic shows the overall authorization procedure between different roles. After the authorization is completed, you can initiate the payment request with accessToken.

Figure 2. Overall authorization process flow

Auto debit

Once the authorization is completed, auto debit payment can be performed as long as the accessToken is valid, without the need to reinitiate authorization for each payment.

1. Call the pay API to initiate the auto debit payment. If the API is called successfully, auto debit succeeds. If the API call failed, auto debit fails.
2. Get the payment result: The asynchronous notification is sent to you by Alipay when the auto debit succeeds or fails. If the pay API call status is unknown, you need to call the inquiryPayment API in the form of polling until getting the payment result:

• If you get the information that the payment is completed successfully, you can proceed with other tasks.
• If the payment is not completed successfully, you need to call the pay API again with a new paymentRequestId.

3. (Optional) When the transaction is successfully paid and still within the cancellable period, or when the transaction is not paid and needs to be canceled in advance before Alipay's payment expiration time, you can call the cancel API to cancel the transaction per your needs. The payment status of the merchant and the user will be kept consistent.
4. (Optional) After the transaction is successfully paid and still within the refundable period, you can call the refund API to issue a refund against the transaction per your needs. You can check the refund status by using the inquiryRefund API.

Notes:

• To obtain accurate payment results, you must integrate both the asynchronous notification and payment result inquiry services. Because some wallets might not return a notification when the payment fails, integrating both the asynchronous notification and payment result inquiry services will ensure the payment result is obtained from any wallet.
• There are various transaction-related amounts and currencies you might use during different integration tasks. For details, see Usage rules of the Amount object.

The following graphic shows the payment procedure and other operations that can be performed after making a payment:

Figure 3. Overall payment process flow

Getting the accurate payment result is very important. Therefore, it is suggested to maintain an order table in the database to contain at least two fields: the order number and the order status. And use the asynchronous notification and payment result inquiry services in the following way:

• Asynchronous notification: Listen to Alipay's asynchronous notifications and make a response upon receiving an asynchronous notification. Then check the order status in the database:

• If the order status is INIT, update the order status according to the asynchronous notification.
• If the order status is not INIT, it indicates that the final payment result has been obtained through inquiry and the order status has been updated accordingly. No further actions need to be taken.

• Payment inquiry: Initiate an active inquiry to the payment result in the form of polling. Before each inquiry, you need to check the order status in the database:

• If the order status is INIT, initiate an inquiry. Update the order status in the database if a final payment result is obtained, otherwise, continue the polling process.
• If the order status is not INIT, it indicates that the inquiry process has been conducted and a final payment result has been obtained and used for updating the order status. No further actions need to be taken.

Figure 4. Use both the asynchronous notification and payment result inquiry services to get the payment result