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

Create accessToken

The accessToken is required to automatically deduct money from the user’s account. To get accessToken, you must get authUrl first and then get authCode.

To get the authUrl and then the authCode, complete the following steps:

  1. Configure the authorization notification receiving address: This ensures you can receive the authorization notification and get the authCode from it even if the reconstructed redirection URL is not returned.
  2. Consult for authUrl: Call the consult API and get authUrl from the corresponding response. authUrl can be used only once during a single authorization process.
  3. Redirect the user: Redirect the user to authUrl by launching the user's payment method app or redirecting to a WEB or WAP page.
  4. Get authCode: After the user agrees to authorize on the page specified by authUrl, the Alipay+ Mobile Payment Partner (MPP) returns a reconstructed redirection URL and Alipay sends you an authorization notification. You can get authCode from the reconstructed redirection URL or authorization notification.
  5. Create accessToken: With the authCode, you can get an accessToken by calling the applyToken API.

Step 1: Configure the authorization notification address

To ensure that you can receive the authorization notification and get the authCode from it, provide the receiving address in Antom Dashboard.

With the address submitted, Alipay sends the authorization result notification when the user authorization succeeds. Upon receipt of the notification, you must return a receipt acknowledgment message to Alipay. To learn how to provide the notification receiving address and return the receipt acknowledgment message to Alipay, see Receive authorization notification.

Step 2: Consult for authUrl

To obtain the authorization URL (authUrl), call the consult API by making a POST request to the Alipay server with the correct request URL path. For example, if you use the domain name of https://open-na-global.alipay.com, the request URL path is: https://<https://open-na-global.alipay.com>/ams/api/v1/authorizations/consult. In the API request, you must specify these fields:

  • authRedirectUrl: The first part of the merchant page URL that the user is redirected to after authorization.
  • authState: A string provided by you that will be used later in the redirection URL. The user will be redirected to the redirection URL after authorization completes.
  • customerBelongsTo: Specify the target Alipay+ MPP that you are requesting authorization for.
  • scopes: Specify the authorization scope per your needs.
  • terminalType: indicates the terminal type of the merchant side.

Request header

Replace the client-id value T_111222333 with the client ID that is assigned to you. You can get the client ID in Antom Dashboard.

copy
Content-Type:application/json; charset=UTF-8
original_host:open-na.alipay.com
Request-Time:2019-07-12T12:08:56+05:30
client-id:T_111222333
Signature:algorithm=RSA256,keyVersion=1,signature=TgpjpAzwmA7aWDloDEitOp

Request body

copy
{
  "customerBelongsTo": "GCASH",
  "authRedirectUrl":"https://www.alipay.com/",
  "scopes": ["AGREEMENT_PAYMENT"],
  "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
  "terminalType": "APP",
  "osType": "IOS",
  "osVersion": "11.0.2"
}

If no response is returned after calling the consult API, call the API again with the same fields as the previous request. If the response is received, response.result represents the result of the API call:

  • When resultStatus is S, the API is called successfully. Only in this case, the value of authUrl is obtained from the response.
  • When resultStatus is U, the API calling status is unknown. You need to call the API again without changing the value of authState.
  • When resultStatus is F, check the reason for failure based on the value of resultCode and take the corresponding action.

The following sample shows a response of a successfully called consult API:

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    },
    "authUrl": "https://render.alipay.com/p/c/jzmcoal2?callback=https%3A%
    "resultInfo": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success." 
     }
}

Step 3: Redirect the user

After getting the authUrl successfully, you need to redirect the user to the authUrl address where the user can agree to authorize. If the redirection process fails, you need to reinitiate the authorization process by calling the consult API again with a new authState value. To ensure the success of the redirection process, see Redirect from merchant to payment method.

If the user is redirected to authUrl successfully, the user can agree to authorize on the corresponding page. After the user agrees to authorize, the corresponding Alipay+ MPP redirects the user back to the merchant side. The merchant address is composed of authRedirectUrl, authCode, and authState. In addition, Alipay simultaneously sends you the authorization notification, which also contains the authCode and authState fields. For more details about the redirection process to the merchant side, see Redirect from payment method to merchant.

Step 4: Get authCode

You can get authCode in one of the following ways if the user agrees to authorize:

  • Get authCode from the reconstructed redirection URL returned by Alipay+ MPPs.
  • Get authCode from the authorization notification.

Note: It is suggested to get authCode from the authorization notification result because a failed redirection might occur. Therefore, you must integrate the notifyAuthorization SPI.

If the authorization process fails because the user does not agree to authorize or fails to authorize, the user will not be redirected to the merchant side or authCode will not be contained in the redirection URL. Usually, if you cannot get authCode within a certain period of time (a suggested time period is 15 minutes), you need to restart from Step 2 to get the authCode again. When calling the consult API again, use an updated value for the authState field in the request.

The reconstructed redirection URL

The reconstructed redirection URL returned by the Alipay+ MPP is the merchant page address composed of the following two parts:

  • The value of authRedirectUrl, which is specified in the consult request.
  • The value of authCode, which is provided by the Alipay+ MPP.
  • The value of authState, which is specified in the consult request.

An example of the redirection URL is given below:

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

After the user is redirected to the reconstructed redirection URL after authorization, you need to check:

  • Whether the value of authState in the URL is consistent with the value of authState specified in the consult request. If the value is inconsistent, the authorization fails and you need to restart the authorization process from Step 2 to get the authCode again.
  • Whether the authCode field has a value. If the authCode field is empty, the authorization fails.

Note: When you test this step in the sandbox, you can open authUrl and use the test payment method and account to simulate a user's authorization.

Step 5. Create the accessToken

After getting the authCode value, you need to call the applyToken API immediately with the value of authCode to obtain accessToken within one minute after obtaining the authCode before authCode expires. Only after getting a valid accessToken, you can directly deduct money from the user's account during the payment phase with no additional operations required for the user to conduct.

Call the applyToken API by making a POST request to the Alipay server with the correct request URL path. For example, if you use the domain name of https://open-na-global.alipay.com, the request URL path is: https://<https://open-na-global.alipay.com>/ams/api/v1/authorizations/applyToken. Specify the following fields in the request:

  • grantType: Assign the AUTHORIZATION_CODE value to this field.
  • customerBelongsTo: Assign the target Alipay+ MPP to this field.
  • authCode: Assign the value of authCode obtained after calling the consult API to this field.

The following sample shows a request body of the applyToken API:

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

The following sample shows a response returned for a successfully called applyToken API. From the response, you can get the value of accessToken. At the same time, the refreshToken used for updating the accessToken is also returned.

copy
{
    "accessTokenExpiryTime": "2019-09-04T13:41:39+0800",
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."     
    },
    "accessToken": "20190828054139156697089972935735984402094237jmfUWaepj
    "refreshTokenExpiryTime": "2019-09-11T13:41:39+0800",
    "resultInfo": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."      
    },
    "refreshToken": "20190828054139156697089972935735984402120180HYYGFvfs
}

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

  • When result.resultStatus is S, the API is called successfully and the accessToken is returned. You can use the accessToken to deduct money from the user's account.
  • 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. Because the authCode can only be used once, if the applyToken API call has failed, you need to restart from Step 2 to get a new authCode and call the applyToken API again.

Note: Each accessToken created by calling the applyToken API has a validity period that varies for different payment methods and users. To prevent transactions from failing due to accessToken invalidation, you can extend the validity period of the accessToken by using the refreshToken before the accessToken expires. It is suggested to maintain a life-cycle table that contains information about the accessToken, periodically retrieve and refresh the accessToken that is about to expire.