Before an automatic deduction can be made, you need to obtain the buyer's authorization. After the authorization is successfully obtained, you need to obtain a payment token using an authorization code. The payment token is used to perform subsequent one-click payments, and you must handle the token properly in the following cases:

• When the payment token for a payment method authorized for Auto Debit is about to expire, you need to refresh the payment token.
• If the buyer deauthorizes the payment method, the payment token needs to be handled accordingly.

Prerequisites

Before you begin, you must complete the following tasks:

• Register on Antom Dashboard.
• Set your keys on Antom Dashboard.
• Configure an address for receiving asynchronous notifications.

For details, see Integration guide.

Obtain the authorization

To obtain authorization from the buyer, complete the following integration steps:

1. Inquire about the authorization URL from Alipay.
2. Redirect the buyer to the payment method authorization page. We recommend that you dynamically render supported payment methods on the payment method authorization page based on the buyer's region.
3. Obtain the authorization code.
4. Apply for a payment token.
5. (Optional) Refresh the payment token.

Step 1: Inquire about the authorization URL from Alipay

After you have signed contracts to support the desired payment methods, you can call the consult API. Alipay will return the authorization URL for obtaining the buyer's authorization in the API response. The URL value will be as follows:

• normalUrl
• schemeUrl
• applinkUrl

Note: In an authorization process, the authorization URL can only be used once. That is, if all three URLs are returned, only one of them can be used.

The authorization URLs that can be returned vary by payment method, which means each payment method may return some or all of these three parameters.

When calling the consult API, pass the following parameters correctly in the request:

• authRedirectUrl: the URL for redirecting the buyer to the merchant page after the authorization is completed. This URL will be used to construct the reconstructed URL in Step 3.
• authState: A string specified by yourself to identify an authorization request. This string will be used to construct the reconstructed URL in step 3.
• customerBelongsTo: specify the target payment method for which you are requesting authorization.
• scopes: Pass in the fixed value AGREEEMENT_PAY.
• terminalType: indicates your client type.

Step 2: Redirect the buyer to the payment method authorization page

Redirect the buyer from your application to the payment method authorization page. During the redirection process, you need to choose the appropriate URL to proceed with the redirection flow based on the buyer's application environment:

• For redirection conducted within a desktop browser, use normalUrl to proceed with the redirection flow.
• For redirection conducted within a mobile browser, we recommend that you refer to the Best practices for configuring the authorization URL.
• For redirection conducted within a mobile application, we recommend that you refer to the Best practices for configuring the authorization URL.

The authorization can be successful or failed. The subsequent redirections in these two cases are as follows:

• Authorization success: The buyer is redirected back to the merchant page, and the page address will be a reconstructed URL composed of the authRedirectUrl, authCode, and authState values.
• Authorization failure:

• If the buyer exits the authorization page, some payment methods allow buyers to be redirected to the merchant page. The address of the merchant page is the authRedirectUrl value.
• If the buyer fails to be redirected to the merchant client from the payment method application due to authorization timeout or failure, we recommend that you guide the buyer to reinitiate the authorization. Usually, if the buyer fails to be redirected to the merchant client from the payment method application after 15 minutes, the authorization fails.

Since the authorization URL can only be used once, if the user authorization fails, you need to call the consult API with a new authState value.

Step 3: Obtain the authorization code

After the buyer's authorization has been obtained, you can obtain the authorization code (authCode) through the following methods:

• Obtain from the reconstructed URL returned by the payment method
• Obtain from the authorization success notification sent by Alipay

Obtain from the reconstructed URL

After the buyer's authorization has been obtained, they will be redirected to the reconstructed URL returned by the payment method. This URL consists of three parts:

• The value of the authRedirectUrl parameter that you passed in the consult API
• The authCode returned by the payment method
• The value of the authState parameter that you passed in the consult API

The following is a reconstructed URL sample:

https://www.alipay.com/?authCode=d2f60253-ecdc-e9bc-27d1- 566970191040&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7

You can obtain the authCode value from the reconstructed URL. However, before using this authCode value, it is necessary to check whether the value of authState in the reconstructed URL is consistent with the value of the authState parameter you passed in the consult API. If it is not consistent, the reconstructed URL is not reliable due to possible malicious events such as attacks during the redirection process. Therefore, authCode in the reconstructed URL cannot be used.

Obtain from authorization notifications

Due to network issues or other reasons, you may not be able to obtain the reconstructed URL. Therefore, you can also obtain the authorization code (authCode) from the authorization notifications provided by Alipay in the following steps.

1. Configure the address for receiving authorization result notifications. For details, see Notifications.
2. After the buyer agrees to the authorization, you will receive an authorization success notification sent by Alipay.
3. After receiving the asynchronous notification, return a response as instructed in the Requirements. Otherwise, Alipay will resend the asynchronous notification.

Note: You can obtain authCode through both the reconstructed URL and the authorization notifications. If you have obtained multiple authCodes, use the one that arrives first and do not use the same authCode value multiple times to apply for payment tokens.

Step 4: Apply for a payment Token

After obtaining the authorization code (authCode), call the applyToken API to obtain a payment token (accessToken). To prevent transaction failure caused by an expired payment token (accessToken), call the applyToken API to get a new access token(accessToken) via refreshToken when the payment token is about to expire.

Obtain a payment token

Call the applyToken API within one minute after obtaining the authorization code (authCode) to apply for the payment token (accessToken). Otherwise, the authorization code (authCode) will expire and become invalid. Only with the payment token (accessToken) can an automatic deduction from the buyer's account be implemented.

When calling the applyToken API, pass the following parameters correctly in the request:

• grantType: Pass in the fixed value AUTHORIZATION_CODE.
• customerBelongsTo: Specify the target payment method for which you are requesting authorization.
• authCode: Pass in the value of authCode that you obtained in Step 3.

The following example is a sample request for applying for the payment token:

{
  "grantType": "AUTHORIZATION_CODE",
  "customerBelongsTo": "GCASH",
  "authCode": "d2f60253-ecdc-e9bc-27d1-566970191040"
}

In the response, you will receive the following key parameters:

• accessToken: the payment token.
• accessTokenExpiryTime: the expiration time of the payment token.
• refreshToken: the refresh token used to refresh the current payment token.
• refreshTokenExpiryTime: the expiration time of the refresh token. Usually, the refreshTokenExpiryTime value is greater than the accessTokenExpiryTime value to ensure the payment method is available. After the refresh token expires, you need to start from Step 1 to obtain a new authorization code (authCode) and then call the applyToken API.

Note:

• If you do not receive a response after calling the API, we recommend that you resend the request with the same parameters and parameter values.
• If you receive a response without the payment token (accessToken), we recommend that you handle it as follows:

• If the value of result.resultStatus is U, resend the request with the same parameters and parameter values.
• If the value of result.resultStatus is F, troubleshoot the issue according to the result code. If you need to call the API again to obtain a payment token, since the authCode can only be used once, you need to start from Step 1 to obtain a new authorization code (authCode) and then call the applyToken API.

• If you want to display the buyer's linked account used for Auto Debit in your client, use the userLoginId value returned through the applyToken API response. The value of this field is desensitized and can be directly displayed.

Refresh a payment token

Once the payment token (accessToken) expires, it can no longer be used for an Auto Debit payment. Therefore, you need to call the applyToken API to refresh the payment token (accessToken) before it expires. To call this API, pass the following parameters in the request:

• grantType: Pass in the fixed value REFRESH_TOKEN.
• customerBelongsTo: Specify the target payment method for which you are requesting authorization.
• refreshToken: Pass in the value of the refresh token parameter (refreshToken). The parameter value is obtained from the applyToken API response that is used to obtain a payment token in the previous steps.

The following example is a sample request for refreshing the payment token:

{
  "grantType": "REFRESH_TOKEN",
  "customerBelongsTo": "GCASH",
  "refreshToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7811"
}

Always use the latest refreshToken value to extend the access token validity period. This is because some payment methods may return a new refreshToken value when you call the applyToken API to refresh the token (when you specify the value of grantType as REFRESH_TOKEN in the applyToken API request).

Note:

• We recommend that you refresh the payment token (accessToken) at least ten days before it expires, so that the Alipay Technical Support team has enough time to handle it. This rule also applies to payment methods with a longer validity period for the payment token (accessToken), such as KakaoPay.
• For payment methods with a longer validity period for the payment token (accessToken), such as KakaoPay, refreshToken and refreshTokenExpiryTime parameters may not be provided.

Payment token lifecycle table

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

Table 1. Access token validity period for different payment methods

We recommend that you maintain a lifecycle table containing information about all payment methods' payment tokens (accessToken), so that you can regularly retrieve expiring payment tokens (accessToken) and refresh them. For example:

Cancel an authorization

When a buyer is to disable the Auto Debit service, they may cancel the service within your client or the payment method client. How they cancel the service determines your required actions:

• If the buyer cancels the service within your client, invalidate the payment token of the payment method using the revoke API. In the API request, pass the payment token (accessToken) used to initiate an Auto Debit payment. After a successful API call, the payment token (accessToken) will become invalid.
• Some payment methods support buyers canceling the Auto Debit service within the payment method client. In this case, you need to configure the address to receive authorization cancellation notifications. When an Auto Debit authorization is canceled within the payment method client, you will receive an authorization cancellation notification. The notification will indicate the payment token (accessToken) that is invalidated for the canceled Auto Debit service. The following example shows an asynchronous notification of an authorization cancellation:

{
  "authorizationNotifyType": "TOKEN_CANCELED",
  "accessToken": "28100103_20215703001538122119",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}

After receiving the asynchronous notification, return a response as instructed in the Requirements. Otherwise, Alipay will resend the asynchronous notification.