Bind the user account

To obtain the user authorization for deducting funds from a specific wallet account, the Acquiring Service Provider (ACQP) must take the following integration steps to enable the user to bind the wallet account with his/her merchant account:

1. Render the payment method page or add payment method page
2. Initiate account binding
3. Retrieve the auth code
4. 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

Different ACQPs provide different service modes, for example:

• some ACQPs provide the payment capability to merchants by packaging the client side and the server side into an integrated service.
• some ACQPs only provide the server side ability, while merchants are required to integrate the Alipay+ client side.

Therefore, for the convenience of developers to read 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 mode.

Workflow

The following figure illustrates the workflow of account binding.

Figure 1. Workflow of binding the user account

Note: The payment method page mentioned in Figure 1 is also known as merchant's cashier page.

The account binding process consists of the following steps:

1. The user chooses to start the account binding process on the payment method page after placing an order or on the add payment method page. (Step 1)
2. Your client side renders the payment method page or add payment method page in the following two steps: (Step 2-6)

1. Your client side consults the information about Alipay+ payment method.
2. Your client side renders the payment method page or add payment method page with the information that is obtained in the previous step.

3. After the user chooses the Alipay+ payment method, your client side initiates the account binding process and opens the Alipay+ wallet page, which displays all the wallets that are supported by Alipay+ and the promotion information corresponding to each wallet. (Step 7-12)

• If the terminal type of your client side is Web and the wallet that the user chooses supports code scanning, the user can open the wallet app to scan the QR code for account binding.
• Otherwise, the user chooses one of the wallets and gets redirected to the authorization URL of the selected wallet for account binding. (Step 13-14)

4. After the user signs the authorization agreement, the user is redirected back to the merchant with an auth code. Meanwhile, Alipay+ notifies your server side of the auth code, which is then synced to your client side. (Step 15 - 19)
5. With the received auth code, your client side initiates a request for the access token via your server side. Your server side sends an applyToken API request to Alipay+, who then returns the access token and information about the newly bound wallet in the synchronous response and a separate asynchronous notification. (Step 20 - 25)
6. After your client side receives the access token, your client side processes the account binding logic and updates the payment method page or add payment method page to display the newly bound wallet to the user. (Step 26 - 27)

Step 1: Render the payment method page or add payment method page

Alipay+ allows you to provide the entry point for account binding on either of the following pages:

• On the payment method page after the user places an order
• On the add payment method page where the user manages the payment methods

Regardless of the page that you use, you need to render the page with the Alipay+ logo and promotion information. To do this, your client side needs to take the following steps:

1. Consult the information about the Alipay+ payment method

Your client side needs to consult the following information about the payment method from Alipay+:

• Whether the Alipay+ payment method is available.
• If available, the Alipay+ logo and promotion information (if any).

Alipay+ provides two methods for you to consult the information about the Alipay+ payment method. The following table shows the details and an applicable scenario that is recommended for each method.

For more information about how to implement these two methods, see How to consult the payment information.

2. Render the payment method page or add payment method page with the information

With the information that is returned in Step 1.1, your client side needs to follow the Alipay+ brand display guidelines to render the payment method page or add payment method page. For more information, see Brand display guidelines for Auto Debit.

Step 2: Initiate account binding

After the user chooses Alipay+ on the payment method page or add payment method page, you need to take the following steps to initiate the account binding process:

1. Integrate the prepare API

Your server side needs to integrate the prepare API provided by Alipay+ to obtain the URL of the Alipay+ wallet page and return it to the client side.

Processing logic

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

• 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 MPP (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. Compared with the URL that is specified on the authRedirectUrl parameter, the complete URL 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 created by the MPP. 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 interface. The value is used to prevent the CRSF attack.

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

• 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"].
• (optional) authNotifyUrl: specifies the URL that is used by Alipay+ to notify your server side of the authorization information, for example, an auth code or an access token is created. This parameter is required if you want to receive the authorization notification from Alipay+. For security reasons, the URL must use HTTPS instead of HTTP.
• paymentAmount: The amount that you request to receive from Alipay+. If the payment amount cannot be provided, set paymentAmount parameter to 0. Set paymentAmount.currency to the currency that you use to create the payment order after account binding succeeds.
• settlementStrategy: The settlement strategy that is applied to the payment order, for example, the currency that you want to be settled against.
• (optional) userRegion: This parameter is used to sort the payment method list in descending order based on the relevance between the MPP and the user region.
• (optional) boundWalletNames: The names of wallets that are already bound with the user account.
• 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 Alipay+ wallet page URL that redirects users to a Web/WAP browser or WebView.

• The following table lists the different results that your server side 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"
}

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

2. Open the Alipay+ wallet page

After your server side handles the prepare API response successfully, your client side needs to further open the Alipay+ wallet page, where the user chooses a wallet that is supported by Alipay+ and gets redirected to the wallet side to confirm authorization.

The redirection from your client side to the wallet client through the Alipay+ wallet page can happen only between certain terminal types of client-side. See the following table for details.

Your client side needs to open the Alipay+ wallet page by using the URL that is returned by your server side. The URL is specified on the normalUrl parameter that is returned in Step 2.1. Depending on the terminal type and the operating system of your client side, the way to open the URL is different. Refer to the following samples for details.

For Android app

try {
    Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(normalUrl));
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); 
    startActivity(intent);
} catch (Exception e) {
    e.printStackTrace();
}

For iOS app

if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0) {
    [[UIApplication sharedApplication] openURL:url options:@{} completionHandler:nil];
}else{
    [[UIApplication sharedApplication] openURL:url];
}

For Web or WAP

window.location.href = normalUrl;

Step 3: Retrieve the auth code

After the previous step, the user is redirected to the wallet's authorization page. After the user confirms authorization at the wallet side, the MPP (wallet) redirects the user back to your client side by using a URL that consists of the authorization redirection URL (authRedirectUrl), auth code (authCode) and auth statement (authState).

The redirection from the wallet side back to the merchant side can happen only between certain terminal types of client-side. See the following table for details.

Asynchronously, Alipay+ calls the authNotify API to send a notification to the URL that you specified on the authNotifyUrl parameter of the prepare API request. The notification also contains the auth code. After receiving the notification, your server side needs to notify your client side of the auth code.

For more information about how to handle the authNotify API 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 or not to use the authCode to call the applyToken API. This is because if the redirection back to your client side fails and you complete the accounting binding by using the authCode from the authNotify API, there is no redirect-back page to inform the user of the account binding result.

Notes:

• It is strongly recommended that your server side integrates the authNotify API to ensure 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's 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 authNotify 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 front 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. Your server side needs to use a separate notification to notify your client side of the auth code after receiving it from Alipay+.

Step 4: Request the access token

After the previous step, you need to request an access token from Alipay+ with the auth code that is retrieved in Step 3. After receiving the access token from your server side, your client side then binds the access token with the user account and updates the payment method page or add payment method page to display the newly bound wallet to the user. The access token is also used by your client side to initiate payments later.

You 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 API response and the authNotify API request provide the accessToken, the one from the applyToken API response is preferred.

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 you need to take into consideration when configuring the request parameters of the applyToken API:

• 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 parameters might be returned in the response:

• walletForAccountBinding: the wallet that is selected by the user for account binding. Returned only if the access token is successfully created.

• The following table lists the different results that you 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, your client side needs to reinitiate the account binding process.

Sample

The ACQP sends an applyToken request to Alipay+.

{
    "authClientId": "2188123412341234",
    "authCode": "281010133AB2F588D14B432312345678",
    "grantType": "AUTHORIZATION_CODE"
}

Alipay+ returns a response to the ACQP.

{
  "acquirerId": "102218800000001234",
  "pspId": "102208800000001234",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  },
  "customerId": "2789808912332134556711234",
  "userLoginId": "62-34312736",
  "accessToken": "281010033AB2F588D14B43238637264FCA5A1234",
  "accessTokenExpiryTime": "2022-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9101234",
  "refreshTokenExpiryTime": "2022-06-08T12:12:12+08:00",
  "walletForAccountBinding": {
        "walletName": "AlipayCN",
        "walletBrandName": "AlipayCN",
        "walletLogo": {
            "logoName": "AlipayCN",
            "logoUrl": "https://www.alipayplus.com/logo/20022222xxx.png"
        }
    }
}

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

2. Handle the authNotify API request

After processing the applyToken API request successfully, Alipay+ asynchronously calls the authNotify API to send a notification to the URL that you specified on the authNotifyUrl parameter of the prepare API 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 API request and return a response, see Receive authorization notification.