Using the Auto Debit product to collect payment is composed of four steps: authorization, auto debit, refund, and settlement. This section provides best practices that all involved parties can follow to integrate Auto Debit successfully.

Fields and definitions

terminalType: the merchant terminal type that the customer uses. Possible values include:

• WEB: indicates the terminal is a PC
• WAP: indicates the terminal is a WAP page
• APP: indicates the terminal is a mobile app

osType: the merchant mobile operating system, including iOS or Android

accessToken: used for customer authorization and auto debit from a specific wallet

refreshToken: used for refreshing the access token when the access token is about to expire

accessTokenExpiryTime: the expiration time of the access token

refreshTokenExpiryTime: the expiration time of the refresh token

authState: an identifier of each customer authorization, used for anti-tamper

authCode: used for getting the access token, which is created and returned to the merchant after customer authorization succeeds

Overall process

The integration process can be illustrated by the following graphic. For the authorization phase, it is suggested to create a table that contains data about access tokens created for each account. When the access token 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.

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

Figure 1. Overall process of Auto Debit integration

Details about how to authorize, make a payment, and make a refund are presented in the following sections.

Authorization

During the authorization process, the merchant obtains the user's access token by calling the consult and applyToken interfaces. The access token is used by merchants to directly deduct money from the user's account during the payment phase, with no additional operations required for the user to conduct.

Authorization experience

The authorization process can be initiated by merchants on a PC website, WAP page, or mobile phone app. This video shows the authorization experience for these terminals.

About access token

For access tokens that are created by consult and applyToken interfaces, the validity period of each token varies for different wallets and users. Before the access token expires, the merchant can extend the validity period of the token by using the refresh token, to prevent transactions from failing due to access token invalidation.

It is suggested to maintain a life-cycle table that contains information about the access token, periodically retrieve the access token that is about to expire, and use the refresh token to refresh the access token.

When a user wants to unbind an access token, the revocation process to invalidate the token can only be initiated by the merchant. The user cannot unbind the access token directly from the wallet. Therefore, the merchant must integrate the revoke interface.

You can read the following sections to get more information about access token creation and management:

• How to create an access token
• How to refresh an access token
• How to invalidate an access token

Access token creation

Steps to create an access token:

1. Call the consult interface to obtain the authorization address (authUrl) of the wallet.
2. The merchant uses the authUrl to enter the wallet authorization page.
3. After the user passes the authentication, the wallet is redirected to the merchant URL (authRedirectUrl) with the authcode and authstate fields.
4. The merchant checks whether the value of the authstate field in the URL is consistent with that in the consult request.
5. The merchant uses the authcode field in the applyToken request, to obtain the access token and refresh token.

Note:

In the preceding steps, authUrl and authcode can be used only once. If the authorization process fails, the merchant needs to call the interface 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.

Figure 2. Overall process of creating an access token

1. Call the consult interface

After receiving the user's request to bind a wallet, the merchant needs to get the authorization address of the wallet by calling the consult interface with the following request URL:

• Sandbox endpoint: /ams/sandbox/api/v1/authorizations/consult
• Production endpoint: /ams/api/v1/authorizations/consult

Figure 3. The process of calling the consult interface

The following fields need to be configured properly in the request:

• request.authRedirectUrl: this indicates the address of the merchant to be redirected to after the wallet authorization is completed. In Auto Debit, the authcode field is contained in the merchant URL. Therefore, it is necessary to ensure that the address can be used for redirection to the merchant side. The following table shows the addresses used for different terminal types:

Table 1. Addresses for different terminal types

Notes:

• For security reasons, the address must be an HTTPS address instead of an HTTP address.
• For the terminal type of app, the acquirer uses a WAP address that can be redirected to a URL scheme, and then the URL scheme can be redirected to the merchant site. In this way, the acquirer does not need to provide different URL schemes for different sub-merchants when calling the consult interface.

• request.terminalType and request.osType: These represent the terminal type of the merchant that the user initiates the request. Please note that these fields do not represent the terminal type of the wallet that the merchant wants to trigger. The details about the fields are as follows:

Table 2. Details about the terminal types and operation system types

Processing of return values:

• If no response is returned, you must call the interface again with the same fields as the previous request.
• If a response is received, response.result represents the consultation result of the authorization status:

• When resultStatus is U, call the interface again without changing the value of authState.
• When resultStatus is F, check the reason for failure based on the value of resultCode.
• When resultStatus is S, authUrl is returned in the response. The merchant page needs to be redirected to the wallet authorization page address specified by authUrl.

Note:

response.authUrl is the address of the wallet authorization page, only when resultStatus is S, this field is returned in the response. The addresses returned for different terminal types are in different types:

Table 3. authUrl for different terminal types of the merchant

2. Redirect to the authorization address

The authorization address is returned by the authUrl field in the response of the consult interface. The merchant uses the value of authUrl to enter the authorization page of the wallet. authUrl can be used only once during one authorization process. If the authorization fails, a consult request needs to be initiated again to get a new authUrl. The way to redirect to the authUrl address differs for different merchant terminal types:

Table 4. The way to open authUrl for different terminal types

For more information about how to open the authUrl address, see Client side integration with wallet.

Notes:

• For the terminal type of app, the corresponding URL needs to be able to open the digital wallet app. Therefore, the merchant needs to open the URL through the system. Do not open the link in app embedded WebView, container, or middle page.
• For more information about the payment terminals each digital wallet supports, see Client side integration with wallet.

3. Redirect to the merchant URL

After passing the authentication in the wallet, the user needs to be redirected to the merchant URL (authRedirectUrl) with the authcode and authstate fields. The merchant only needs to use the authcode and authstate fields:

1. Check whether the value of the authstate field in the URL is consistent with that in the consult request.
2. Check whether the authCode field has a value. If the authCode field is empty, the authorization fails. If the authCode field is not empty, the value of authCode is to be used for calling the applyToken interface.

If the user does not start the authenticate process or the authentication process fails, the user will not be redirected to the merchant URL or no authCode is contained in the redirection process. Therefore, the merchant cannot obtain the authCode field. If the merchant does not get authCode within a certain period of time (a suggested time period is 15 minutes), the authorization process needs to be abandoned. If the user needs to rebind, the consult interface is to be initiated again by the merchant.

The authorization process from the wallet page to the merchant page has different redirection paths for different terminal types. The merchant page is specified by the authRedirectUrl field of the consult interface.

Table 5. The way to redirect to the merchant page for different terminal types

4. Call the applyToken interface

After getting the authCode value, the applyToken interface is to be called by the backend system immediately in case authCode expires. The merchant needs to call the applyToken interface within one minute after obtaining the authCode with the following request URL:

• Sandbox endpoint: /ams/sandbox/api/v1/authorizations/applyToken
• Production endpoint: /ams/api/v1/authorizations/applyToken

Figure 4. The process of calling the applyToken interface to get an access token

Processing of return values:

• If no response is returned, you must call the interface again with the same fields as the previous request.
• If a response is received, take the following actions for each case:

• response.result indicates the result of calling the applyToken interface:

• When result.resultStatus is S, the authorization is successful.
• When result.resultStatus is U, call the interface again with the same fields as the previous request.
• When result.resultStatus is F, the merchant needs to take corresponding actions according to resultCode. Because the authCode can only be used once, the merchant needs to call the consult interface again to reinitiate an authorization process.

• response.accessToken is the access token after the authorization is completed, which is returned only when result.resultStatus is S.
• response.accessTokenExpiryTime is the expiration time of the access token. If the merchant uses the access token to initiate payment after the access token expires, the payment is to be failed.
• response.refreshToken is used to refresh the validity period of the access token before the accessToken expires.
• response.refreshTokenExpiryTime is the expiration time of the refresh token. Usually, refreshTokenExpiryTime is greater than accessTokenExpiryTime to ensure that refreshToken is usable. If the merchant tries to refresh the validity period of the access token after the refresh token expiration time, there is no guarantee that every wallet will be refreshed successfully.

Access token refresh

Due to risk control requirements, digital wallets in different countries have different validity periods for access tokens. The minimum validity period is one year. The following table shows the validity period of Alipay+ MPP wallets:

Table 6. Access token validity period for different wallets

The merchant needs to refresh the access token before the access token expires. We suggest refreshing the access token at least 10 days before the access token expiration so that Alipay technical support team has enough time to take corresponding actions. Therefore, use the following mechanism to determine the time to initiate the access token refresh process:

When the current date is less than 10 days from the date specified by accessTokenExpiryTime, call the applyToken interface to refresh the validity period of the access token with the following request URL:

• Sandbox endpoint: /ams/sandbox/api/v1/authorizations/applyToken
• Production endpoint: /ams/api/v1/authorizations/applyToken

For wallets with long access token validity periods, such as KakaoPay, the same rule applies. Therefore, the applyToken interface will not be called until the preset date.

Figure 5. The process of refreshing the access token

The following fields need to be configured properly in the request:

• grantType: The value is REFRESH_TOKEN for the token refresh process.
• refreshToken: This is a required field. The value of this field is also the value of refreshToken in the response of the applyToken interface when the applyToken interface is called for creating the access token. When using refreshToken to initiate a request, ensure to initiate a call to refresh the token before the accessToken expires.

Processing of return values:

• If no response is returned, you must call the interface again with the same fields as the previous request.
• If a response is received, take the following actions for each case:

• response.result indicates the result of calling the applyToken interface:

• When result.resultStatus is S, the validity period of the access token is refreshed successfully.
• When result.resultStatus is U, the merchant needs to call the interface again with the same fields as the previous request.
• When result.resultStatus is F, the merchant needs to take corresponding actions according to resultCode.

• response.accessToken is the access token after the refresh process is completed, which is returned only when result.resultStatus is S. Use this value for the auto debit payment process.
• response.accessTokenExpiryTime is the expiration time of the access token after the refresh process is completed.
• response.refreshToken is used to elongate the validity period of the access token before the accessToken expires, which is returned only when result.resultStatus is S.

Notes:

• Because some wallets might update the value of refreshToken after calling the applyToken interface with grantType of REFRESH_TOKEN, the merchant needs to use the latest refreshToken to elongate the access token validity period.
• Wallets with a long validity period for the access token do not provide the refreshToken and refreshTokenExpiryTime fields, such as Kakaopay.

Access token invalidation

The user cannot revoke the access token in the wallet. The merchant needs to integrate the revoke interface and initiate the access token revocation process for users with the following request URL:

• Sandbox endpoint: /ams/sandbox/api/v1/authorizations/revoke
• Production endpoint: /ams/api/v1/authorizations/revoke

Figure 6. The process of invalidating the access token

Processing of return values:

• If no response is returned, you must call the interface again with the same fields as the previous request.
• If a response is received, take the following actions for each case:

• response.result indicates the result of calling the revoke interface:

• When result.resultStatus is S, the revocation is successful.
• When result.resultStatus is U, the merchant needs to call the interface again with the same fields as the previous request.
• When result.resultStatus is F, the merchant needs to take corresponding actions according to resultCode.

Note:

If the revocation process succeeds, the access token becomes invalid. If the access token is still used for the auto debit payment, the payment will be failed.

Auto debit payment

After the user completes authorization, the merchant can directly initiate auto debit payments with the access token. There is no need to go through the authorization process again for each payment. For auto debit payments, the pay, inquiryPayment, notifyPayment and cancel interfaces are required to be integrated.

Figure 7. Process of initiating the payment, inquiry, and cancellation process

• The user selects a wallet to initiate the payment. The merchant client obtains the user information, order amount, and selected wallet, and calls the interface in the merchant server to place an order. (Step 1)
• The merchant server calls the Alipay pay interface. (Step 2)
• Alipay returns the payment result. (Step 4)

• If the value of result.resultStatus is S or F, the merchant does not need to initiate the inquiryPayment interface or update the order status when receiving the asynchronous notification. (Step 5)
• If the value of result.resultStatus is U, the merchant needs to update the order status when receiving the asynchronous notification, or initiate the inquiryPayment interface to get the final payment result. (Step 5)

• The merchant server obtains the payment result by receiving the notification from notifyPayment and actively calling the inquiryPayment interface. (Step 6)
• If the merchant wants to abandon the transaction before obtaining the final payment result (SUCCESS or FAIL), the merchant needs to call the cancel interface. If the merchant wants to abandon the transaction when it has been paid successfully, the merchant still needs to call the cancel interface. By calling the cancel interface, the payment status of the merchant and the user will be kept consistent. (Step 8)
  
• The merchant updates the internal order status and shows the payment result to the user. (Step 10)

Payment result inquiry

To obtain the payment result, the merchant needs to monitor the asynchronous notification or actively calling the inquiryPayment interface to get the payment result. Although a retransmission mechanism exists for the asynchronous notification, the asynchronous notification might not be received due to network issues when the user successfully completes the payment. Therefore, it is necessary to actively inquire the payment result with the inquiryPayment interface.

Payment expiration time

For auto debit products, Alipay's payment expiration time is 1 minute. The merchant can call the inquiryPayment interface in the form of polling to get the final payment result. The polling time needs to be longer than 1 minute.

Final payment results

In the response of the inquiryPayment interface, the following statuses indicate the final payment result:

• SUCCESS: The payment succeeded.
• FAIL: The payment failed.
• CANCELLED: The payment was canceled.

Besides the above-mentioned final payment results, the response might also be an intermediate status:

• PROCESSING: The payment is in progress. If this result is returned, the merchant needs to continue calling the inquiryPayment interface until a final payment result (SUCCESS, FAIL, or CANCELLED) is obtained.

Transaction cancellation

For payment scenarios with a specific transaction closing time of the merchant, for example, a flash sale, hotel reservation, or flight ticket purchase, conform to the following rule to ensure payment result consistency between the merchant and the user:

When the following conditions are all met:

• The merchant does not receive the notification.
• No final payment result is returned for the inquiryPayment interface.
• The merchant needs to close the transaction in advance before Alipay's payment expiration time (1 minute).

The cancel interface needs to be called to cancel the transaction to avoid payment result inconsistency between the merchant and user. As long as the merchant initiates the cancellation request, Alipay will guarantee that the transaction will be canceled or refunded. By calling the cancel interface, the transaction will be canceled if the user has not completed the payment, or refunded if the user has completed the payment.

Call the pay interface

Call the pay interface to initiate an auto debit with the following request URL:

• Sandbox endpoint: /ams/sandbox/api/v1/payments/pay
• Production endpoint: /ams/api/v1/payments/pay

The following fields need to be configured properly in the request:

• request.paymentMethod.paymentMethodId : represents the access token obtained after the user completes authorization.

Processing of return values:

• If no response is returned, call the interface again with the same fields as the previous request.
• If a response is received, take the following actions for each case:

• response.result.resultStatus: indicates the result of the payment:

• S: This indicates the payment succeeds.
• F: This indicates the payment fails. For more information about the reason for failure, see resultCode.
• U: This indicates the payment is still in process. In this case, the inquiryPayment interface needs to be called until the value of paymentStatus is SUCCESS, FAIL, or CANCELLED, or until the asynchronous notification is received.

• response.paymentAmount: This indicates the amount of the payment, which can be used for reconciliation.
• response.paymentCreateTime: This indicates the time when the payment was initiated.
• response.paymentTime: This indicates the time when the payment is completed. If the payment fails, this field is not to be returned.

Process payment result

To obtain accurate payment results, the merchant must integrate both the asynchronous notification and payment result inquiry services. Because some wallets might not return any notification when the payment fails, therefore, integrating both the asynchronous notification and payment result inquiry services will ensure the payment result being obtained from any wallet.

When the payment is complete, the Alipay server sends an asynchronous notification to inform the merchant of the corresponding payment result. However, for some wallets, asynchronous notifications will not be sent when the payment fails. The asynchronous notification also does not have a 100% delivery guarantee.

Therefore, it might occur that the user completes the payment but the merchant does not receive the payment result. To avoid this situation, merchants must integrate the payment result inquiry service to inquire the payment result constantly in a form of polling.

It is suggested to use the asynchronous notification and payment result inquiry services in the following way:

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

• The merchant needs to maintain an order table in the database to contain at least two fields: the order number and order status.
• Asynchronous notification: The merchant needs to 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.
• Inquiry: The merchant needs to initiate an active inquiry to the payment result in the form of polling. Before each inquiry, the merchant needs 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.

Asynchronous notification

After the merchant integrates the notifyPayment interface, Alipay sends the user's payment result to the merchant according to the following rules:

• If the payment succeeds, the asynchronous notification is sent to the merchant immediately.

•​ If the payment fails, the asynchronous notification is sent to the merchant after the 1-minute Alipay payment expiration time.

• If the user does not pay, the asynchronous notification is sent to the merchant after the 1-minute Alipay payment expiration time.

After receiving the asynchronous notification, the merchant needs to return SUCCESS to Alipay immediately. No digital signature is required. This message represents a successful receipt of the payment notification. The code sample is as follows:

{
 "result": {
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
     }

If the merchant doesn't send such a response to Alipay for the asynchronous notification, or the merchant response is not delivered to Alipay successfully due to network reasons, Alipay will automatically resend the asynchronous notification within 24 hours for up to 8 times or until the correct response is received. The sending intervals are as follows:

0 minute, 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, 15 hours

Fields in the notifyPayment request need to be understood correctly:

• notifyType: The value is PAYMENT_RESULT for this case.
• result.resultStatus: This field indicates the payment result of the order. Possible values include:
• S: This indicates the payment succeeds.
• F: This indicates the payment fails. The failure reason is indicated in resultCode.

Note: The value of U, which represents an unknown status, is not used in this interface.

• paymentRequestId: This field is assigned by the merchant to identify each unique request.
• paymentId: The unique ID that is assigned by Alipay to identify a payment.
• paymentAmount: This field represents the amount that the user paid. The merchant can use the value of this field for comparing amounts.
• paymentCreateTime: This field indicates the time that the payment was created
• paymentTime: This field indicates the time that the payment was completed. If the payment was failed to be paid, this field is not returned.

Inquiry

Merchants can initiate the inquiryPayment interface to inquire the payment result after completing the pay interface calling, or when the payment result notification is not received within 1 minute after receiving the response of the payment request. The following fields in the inquiryPayment interface need to be understood correctly:

Fields in request:

• paymentRequestId: This field is assigned by the merchant to identify each unique request. It is suggested to use this field for the inquiry process.

Fields in response：

• result: This field only indicates the calling status of this inquiry request. It does not indicate the payment status.
• paymentStatus: This field indicates the payment status of the order. This field is returned only when the value of result.resultStatus is S. The value of this field can be:
• SUCCESS: This value indicates the payment succeeds. As this is a final payment status, the merchant can stop the inquiry process.
• FAIL: This value indicates the payment failed. As this is a final payment status, the merchant can stop the inquiry process.
• CANCELLED: This value indicates the payment is canceled. As this is a final payment status, the merchant can stop the inquiry process.
• PROCESSING: This value indicates that the payment is still processing. This is an intermediate payment status. When this value is returned, the merchant needs to continue the inquiry process in the form of polling until a final payment status is obtained or until the asynchronous notification is received. The polling time needs to last for at least 1 minute (Alipay's payment expiration time).

Cancel the transaction (if required)

If the merchant deals with payment scenarios that have a specific transaction closing time, the cancel interface must be integrated. The merchant can initiate a payment cancellation in one of the following cases:

• After the payment is successful and within the cancellable period. There is no fee charged for cancellation, but the cancellable period is usually only one day.
• During the payment process, when the polling process cannot get a final payment result. The merchant can choose to terminate the transaction by calling the cancel interface to keep the transaction status consistent between the user and merchant sides.

The following fields in the cancel interface need to be understood correctly:

Fields in request:

• paymentRequestId: This field is assigned by the merchant to identify each unique request. It is suggested to use this field for the cancellation process.

Fields in response：

• result.resultStatus: This field indicates the cancellation result:
• S: This value indicates that the cancellation succeeded.
• F: This value indicates that the cancellation is failed. Take further actions according to resultCode.
• U: This value indicates that the cancellation result is unknown. Use the same request parameters to retry the cancellation request. If the merchant calls the cancel request calling three times and still gets U, contact Alipay Technical Support.
• paymentId: This field is assigned by Alipay to identify each unique request.
• paymentRequestId: This field is assigned by the merchant to identify each unique request.
• cancelTime: The time when the payment cancellation succeeds.

Refund

For transactions that are successfully paid, the merchant can initiate a refund by calling the refund interface or manually initiate a refund through the merchant's back-end. The refundable period is determined by the contract, which is usually 12 months. The request URL is one of the following options:

• Sandbox endpoint: /ams/sandbox/api/v1/payments/refund
• Production endpoint: /ams/api/v1/payments/refund

Figure 8. Refund process

Processing of return values:

• If no response is returned, you must call the interface again with the same fields as the previous request.
• If a response is returned, the value of response.result.resultStatus indicates the refund status:

• S: This indicates the refund succeeds.
• U: This indicates the refund is in an uncertain status. You must call the interface again with the same fields as the original request.
• F: This indicates that the refund fails. Further actions that needs to be taken are indicated by the resultCode field. For example, if a result code of MERCHANT_BALANCE_NOT_ENOUGH is returned, it indicates that the balance of the merchant to be settled is insufficient. That is, the balance of the merchant to be settled is less than the refund amount. Therefore, the merchant needs to wait until successful payments are generated and the balance of the merchant to be settled is greater than the refund amount of the transaction, then initiate the refund process again. When reinitiating the refund process, the value of request.refundRequestId must be updated.

• response.refundAmount: indicates the refund amount, which can be used for reconciliation.

Note:

The difference between the action of refund and the action of canceling a transaction:

• The refundable and cancellable period are specified by the contact. By default, the refundable period is 12 months and the cancellable period is 1 day.
• Fees will be charged for the refund process, while there are no fees to cancel a transaction.
• The refund process can be used only for a successfully paid transaction. The cancellation process is used for a transaction that does not receive a final payment result of success or failure and is used when the merchant needs to abandon the transaction.
• The refund process supports partial refund of the transaction, while the cancellation process cancels the entire transaction.

About the payment amount and currency

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 subfields of currency and value. And all currency fields of Alipay APIs or reports follow the same definition.

Amount

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.

Smallest unit for different currencies

Table 3. Details about the currency.

Minimum payment or refund amount

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.