Refresh accessToken

You need to refresh the accessToken when the accessToken is about to expire. An expired accessToken cannot be used for deducting money from the user's account. Therefore, you need to call the applyToken API to get an updated accessToken before the accessToken expires.

Each accessToken has a validity period and is accompanied by a refreshToken. The accessToken expiration time can be obtained from the accessTokenExpiryTime field when you call the applyToken API to create the accessToken. After the validity period, the accessToken expires and cannot be used for deducting money.

To refresh the accessToken, call the applyToken API by specifying the following fields:

• grantType: Assign the REFRESH_TOKEN value to this field.
• customerBelongsTo: Assign the target Alipay+ MPP to this field.
• refreshToken: Assign the value of refreshToken obtained from a successfully called applyToken API when creating the accessToken.

Each refreshToken also has an expiration time, which is indicated by refreshTokenExpiryTime of the applyToken response. Usually, refreshTokenExpiryTime is greater than accessTokenExpiryTime to ensure that refreshToken is usable. If you try to refresh the validity period of the accessToken after the refreshToken expiration time, there is no guarantee that every payment method will be refreshed successfully. In addition, you always need to use the latest refreshToken to elongate the accessToken validity period, this is because some payment methods might update the value of refreshToken after calling the applyToken API with the value of grantType specified as REFRESH_TOKEN.

It is suggested to refresh the accessToken at least 10 days before the accessToken expiration so that Alipay technical support team has enough time to take corresponding actions. Therefore, when the current date is less than 10 days from the date specified by accessTokenExpiryTime, you need to call the applyToken API to refresh the validity period of the accessToken. For payment methods with long access token validity periods, such as KakaoPay, the same rule applies.

Note: Wallets with a long accessToken validity period (such as KakaoPay) do not provide the refreshToken and refreshTokenExpiryTime fields.

Due to risk control requirements, digital payment methods 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 payment methods:

Table 1. Access token validity period for different payment methods

After calling the applyToken API to refresh the accessToken, the following cases might occur:

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

• When result.resultStatus is S, the validity period of the accessToken is refreshed successfully. A new accessToken and its expiration time (accessTokenExpiryTime) and the corresponding refreshToken are returned.
• When result.resultStatus is U, call the API again with the same fields as the previous request.
• When result.resultStatus is F, take corresponding actions according to resultCode.