Account binding is a process for merchants to obtain the user authorization for deducting funds from a specific wallet account.

To enable account binding, the Acquiring Service Provider (ACQP) must complete the following integration steps so that the user can bind their wallet account to their merchant account.

• Step 1. Initiate account binding
• Step 2. Retrieve the auth code
• Step 3. Request the access token

With Alipay+ support, the user can bind multiple wallets with the same merchant account, and one wallet account can be bound with multiple merchants. If any regulation on the number of merchants exists in a country/region, comply with the regulation.

Before you begin

Ensure that the merchant information is registered before processing account binding. For more information, see Merchant registration.

Different ACQPs provide different service modes, for example:

• Some ACQPs provide both client-side and server-side capabilities as an integrated service.
• Some ACQPs provide only server-side capabilities, and require merchants to integrate directly with the Alipay+ client side.

Therefore, for the convenience of developers reading this document, no matter which service mode is used, "your client side" and "your server side" are used uniformly to refer to the corresponding client side and server side in different service modes.

Workflow

The merchant needs to design the entrance of starting an account binding process. After the user decides to start the process, the merchant and the ACQP need to implement the account binding process as described below.

The following figure illustrates the workflow of account binding.

Figure 1. Account binding workflow

The account binding workflow contains the following key steps:

1. The user chooses to start the account binding process at the merchant side. (Step 1)
2. After the user selects one of the Alipay+-supported wallets, the merchant requests the authorization URL from Alipay+ via the ACQP and redirects the user to the returned URL. (Step 2 -7)
3. After the user signs the authorization agreement, the user is redirected back to the merchant with auth code. Meanwhile, Alipay+ sends a notification that includes the auto code to the ACQP, who then further forwards the notification to the merchant. (Step 8 - 13)
4. With the received auth code, the merchant initiates the request for the access token via the ACQP. The ACQP calls the applyToken API from Alipay+, and Alipay+ then returns the access token in the synchronous response and a separate asynchronous notification. (Step 14 - 20)
5. After the merchant receives the access token from Alipay+ via ACQP, the merchant processes the account binding logic and displays the binding success result to the user. (Step 21 - 22)

Note: To obtain available wallet information, you can:

• Call the consultPayment API to receive information about payment methods, including wallet logos.
• Call the inquiryRegistrationStatus API to retrieve the merchant registration result. For Alipay+ brand logo images, use the Acceptance Mark Generator to download the approved assets. For the correct brand name text, refer to the Brand name list.

Step 1. Initiate account binding

The ACQP needs to call the prepare API from Alipay+ to get the authorization URL information and return it to the merchant.

The following figure illustrates the process of requesting the authorization URL:

Figure 2. Requesting Authorization URL process

Processing logic

• The following list provides the key information that the ACQP needs to take into consideration when configuring the request parameters of the prepare API:

• authClientId: specifies the unique id of the auth client to whom the user grants authorization. Normally the auth client refers to the merchant.
• authClientName: specifies the legal name of the auth client. Normally it is the legal name of the merchant.
• (optional) authClientDisplayName: specifies the display name of the auth client, which is displayed at the Wallet side. Normally it is the merchant's business name.
• (optional) authClientLogo: specifies the URL of the auth client's logo. It is provided by the auth client. Normally it is the logo file of the merchant. The logo can be displayed on the authorization page in the wallet if this field is provided.
• authState: specifies the authorization statement that is provided by the auth client.
• authRedirectUrl: specifies authorization redirection URL, of which the domain name is provided by the auth client. This URL will be used by the Mobile Payment Provider (wallet) to reconstruct a complete URL that redirects the user back to the merchant when the user completes the authorization process at the wallet side. Versus the URL that is specified on the authRedirectUrl parameter, the complete URL reconstructed is carried with the two additional parameters:

• authCode: the auth code that is used later by the auth client to obtain the access token. The auth code is generated by the Mobile Payment Provider. For more information about the auth code, see Retrieve the auth code.
• authState: the auth statement that is specified on the authState parameter of the prepare API. The value is used to prevent the CRSF attack.

The following example shows a format of the complete URL that is constructed based on the authorization redirection URL: https://www.merchant.com/authorizationResult?authCode=281010133AB2F588D14B432312345678&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7

• customerBelongsTo: specifies the name of the wallet that the customer selects. It must be set to the value of the walletName field that is returned in the response of the consultPayment API.
• scopes: specifies the authorization scope. Set the value as required. In this account binding scenario, the value must be set as ["AGREEMENT_PAY", "USER_LOGIN_ID"]. For more information about the authorization scopes that you can use, see the specification of the prepare API.
• (optional) referenceAgreementId: specifies the unique ID that is assigned by the auth client to identify the current authorization.
• (optional) authNotifyUrl: specifies the URL that is used by Alipay+ to notify the ACQP of the authorization information, for example, an auth code or an access token is created. This field is required when the ACQP wants to receive the authorization notification from Alipay+. For security reasons, The URL must use HTTPS instead of HTTP.
• terminalType, osType: specifies the information of the terminal type and operating system of the merchant. terminalType is required, and osType is required when the terminal type is APP or WAP.

• The following parameters might be returned in the response:

• normalUrl: The Web/WAP URL that redirects users to a Web/WAP page in the browser or the WebView.
  

• The following table lists the different results that the ACQP might receive from Alipay+.

Sample

The ACQP sends a prepare request to Alipay+.

{
    "paymentAmount": {
        "currency": "JPY",
        "value": "100"
    },
    "settlementStrategy": {
        "settlementCurrency": "JPY"
    },
    "userRegion": "JP",
    "authClientId": "2188123412341234",
    "authClientName": "Merchant",
    "authClientDisplayName": "Merchant display",
    "referenceMerchantId": "2188123412341230",
    "authRedirectUrl": "https://www.merchant.com/authenticationResult?param1=123&param2=234",
    "scopes": [
        "AGREEMENT_PAY"
    ],
    "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
    "terminalType": "WEB",
    "referenceAgreementId": "aNDJWQNNabdad1234",
    "osType": "IOS",
    "osVersion": "11.0.2",
    "authNotifyUrl": "https://www.merchant.com/authenticationNotify?referenceAgreementId=aNDJWQNNabdad1234"
}

Alipay+ returns a response to the ACQP.

{
    "acquirerId": "102218800000001234",
    "pspId": "102208800000001230",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    },
    "normalUrl": "https://openauth.xxx.com/authentication.htm?authId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3",
    "appIdentifier":"com.alipay.xxx"
}

More Information

For more information about how to use the prepare API (such as the field description and format), see the prepare API.

Step 2. Retrieve the auth code

The following figure illustrates the process of retrieving the auth code:

Figure 3. Workflow of retrieving the auth code

After the previous step, the merchant needs to redirect the user to the wallet's authorization page. After the user confirms authorization on the authorization page, the Mobile Payment Provider (wallet) redirects the user to the page of the URL, which consists of the authorization redirection URL (authRedirectUrl), auth code (authCode) and auth statement (authState).

Asynchronously, Alipay+ calls the authNotify API to send a notification to the URL that the ACQP has specified on the authNotifyUrl parameter of the prepare API. The notification also contains the auth code. After receiving the notification, the ACQP needs to notify the merchant of the auth code.

For more information about how to handle the authNotify request and return a response, see Receive authorization notification.

You need to retrieve the auth code for the succeeding request for an access token as follows:

• If both the authNotify API and the authorization redirection URL provide the authCode, the one from the authorization redirection URL is preferred.
• If only the authNotify API provides the authCode, you must decide whether to use that code to call the applyToken API. This is because If redirection back to your client side fails and account binding is completed using the authCode from the authNotify API, there will be no redirect-back page to inform the user of the account binding result.

Notes:

• It is strongly recommended that the ACQP integrate the authNotfify API to ensure the authorization success. Because in scenarios where the merchant uses a WAP page and the wallet uses an app, the user's login session can be lost as the wallet redirects the user back to the user's default browser, which might not be the browser of the merchant WAP page. In this case, the authorization cannot be continued. This is especially prone to happen for some wallets, such as AlipayCN and Kakao Pay, which only support authorization in apps. However, if the authNotfify API is used to obtain the auth code, the merchant can continue with the authorization as there is no need to check the user's login session in the fron end.
• Since the redirection from the wallet to the merchant after the user completes authorization relies on the URL redirection, the process might be interrupted for some reason. The ACQP needs to use a separate notification to notify the merchant of the auth code after receiving it from Alipay+.

Step 3. Request the access token

The following figure illustrates the process of requesting an access token:

Figure 4. Flow to use authCode to retrieve accessToken from Alipay+

On behalf of the merchant, the ACQP calls the applyToken API to request an access token from Alipay+ with the auth code that is retrieved in Step 2. After receiving the access token from the ACQP, the merchant then binds the access token with the user account and renders the binding success result. The access token is also used by the merchant to initiate a payment via the ACQP.

The ACQP can obtain the access token in the following two ways:

• from the synchronous response of the applyToken request
• from the asynchronous notification that is sent by Alipay+ by calling the authNotify API after processing the applyToken request. Integration of the authNotify API is optional but recommended.

Note: If both the applyToken response and the authNotify request provide the accessToken, the one from the applyToken response is preferred.

3.1. Integrate the applyToken API

Your server side needs to integrate the applyToken API provided by Alipay+ to request the access token.

Processing logic

• The following list provides the key information that the ACQP needs to take into consideration when configuring the request parameters of the applyToken API to obtain an access token:

• authClientId: the unique identifier for the auth client. Normally it is a unique ID for the merchant.
• grantType: to request an access token with the auth code, set the grant type as AUTHORIZATION_CODE.
• authCode: use the auth code that is received from Alipay+ in Step 3.

• The following table lists the different results that the ACQP might receive from Alipay+.

Note:

The access token application request must be initiated within 3 minutes once the authorization code is obtained. If the interval time exceeds 3 minutes, the merchant needs to reinitiate the account binding process.

Sample

The ACQP sends an applyToken request to Alipay+.

{
    "authClientId": "218xxxxxxxxx1234",
    "grantType": "AUTHORIZATION_CODE",
    "authCode": "281010133AB2F588D14B43231234****"
}

Alipay+ returns a response to the ACQP.

{
    "acquirerId": "102xxxxxxxxxxx0001",
    "pspId": "102xxxxxxxxxxx0001",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    },
    "accessToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAF35",
    "accessTokenExpiryTime": "2019-06-06T12:12:12+08:00",
    "refreshToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7811",
    "refreshTokenExpiryTime": "2019-06-08T12:12:12+08:00",
    "customerId": "27898089xxxxxxxxxxxxxxxx1",
    "userLoginId": "138******27"
}

For more information about how to use the applyToken API (such as the field description and format), see the applyToken API.

3.2. Handle the authNotify request

After processing the applyToken request successfully, Alipay+ asynchronously calls the authNotify API to send a notification to the URL that you specified in the authNotifyUrl parameter of the prepare request. The notification also contains the access token. After receiving the notification, your server side needs to notify your client side of the access token.

For more information about how to handle the authNotify request and return a response, see Receive authorization notification.