Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

How to obtain Alipay user_id

The Alipay user ID (buyer_id) is one of the required request parameters of the alipay.acquire.create interface. To complete a payment transaction, you need to obtain the Alipay user ID by completing the following steps:

1.Build the openauth link and guide the user to visit this link.

The URL format for the openauth link is as below:

https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=auth_base&redirect_uri=ENCODED_URL

2.Get the auth_code.

The user is automatically redirected to the pre-defined callback page, and Alipay adds auth_code, app_id, scope and other request parameters into the callback URL. 

An example of the request is as below:

http://example.com/doc/toAuthPage.html?app_id=2014101500013658&source=alipay_wallet&scope=auth_base&auth_code=ca34ea491e7146cc87d25fca24c4cD11

Among which, the value of the auth_code parameter isca34ea491e7146cc87d25fca24c4cD11

3.Get the user ID by using the auth_code.

The auth_code parameter can be used as the token to obtain Alipay user ID by calling the Alipay.system.oauth.token API. The returned auth_code is unique in each authorization. Each auth_code can be used only once and becomes expired automatically in one day.


Notes about the authorization API:

  • The user authorization code: auth_code

The auth_code can be used only once. The auth_code is valid for 3 minutes to 24 hours. Even if the auth_code is not used, the auth_code cannot be used when the validity period expires. A new auth_code is generated for each authorization action by the user.

You are recommended to call the alipay.system.oauth.token API as soon as possible after obtaining the auth_code, to exchange for the access token (access_token).

  • The authorization scope:

The scope is an open resource and can be used without applying for a permission. One or more user authorization scopes can be included in an authorization request. Each authorization scope contains several Alipay-provided APIs and each scope needs to be separated by a comma. The scopes of authorization for different business scenarios can be designed differently and you need to use the corresponding scope parameter correctly. The validity period of the scope affects the validity period of the access_token and refresh_token. For the validity period of different scopes, please refer to the specific product documentation.

Excessive authorization scope will easily lead users to give up authorization. You are advised to use only the auth_base or auth_user in the login scenario. After that, you can guide the user to request user authorization for a specific scope according to the specific business needs.

  • The access_token:

The validity period of the access_token depends on the scope validity period. If multiple scopes are specified during authorization, the validity period of the final access_token depends on the scope with the shortest validity period.

The access_token becomes effective when the alipay.system.oauth.token is called and an expires_in value is returned. The access_token expires after the expires_in-determined time.

Token storage requirements:

  1. Ensure that the access_token is safely saved;
  2. Save the access_token by indexing with the appID plus UID plus a single scope. Otherwise, the access_token cannot be used correctly, which leads to an API calling error. If the scopes for several authorization processes are the same, save only the access_token with the longest authorization expiration period.
  3. Users can cancel the authorization. If the authorization is cancelled by a user, the access_token cannot be used even though it is still within the validity period.
  • The refresh_token:

When you use the auth_code to call the alipay.system.oauth.token API to get the access_token, a refresh_token is returned. During the validity period of the refresh_token, you can also use the refresh_token to call the alipay.system.oauth.token API and get a new access_token.

The validity period of the refresh_token depends on the validity period of the scope specified during authorization. If multiple scopes are specified during authorization, the validity period of the refresh_token depends on the scope with the shortest expiration period. The refresh_token becomes effective when the alipay.system.oauth.token is called and an re_expires_in value is returned. The refresh_token expires after the re_expires_in-determined time.

Note:

  1. When you use the refresh_token to call the alipay.system.oauth.token API and then get a new access_token, the previous access_token becomes invalid immediately and the deadline of the access_token is recalculated because of a remained value of expires_in. A new refresh_token is returned so that the previous refresh_token becomes invalid, however, the new refresh_token deadline is not recalculated because the value of re_expires_in reduces.
  2. Users can cancel the authorization. If the authorization is cancelled by a user, the refresh_token cannot be used even though it is still within the validity period.