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

This topic guides you through the steps that the Mobile Payment Provider (MPP) needs to take to implement account binding.

Depending on the terminal type of the MPP client, the MPP can implement account binding in different ways:

• If the terminal type of the MPP client is App, the MPP can use the Alipay+ client SDK to facilitate the account binding processing quickly and efficiently.
• If the terminal type of the MPP client is WAP/Web, the MPP needs to directly integrate the required APIs, render the Authorization page, and redirect the user back to the merchant manually.

Note: If a business has more than one merchant account, the MPP must allow one wallet account to be bound with multiple merchant accounts. If the number of merchant accounts that can be bound with one wallet account is limited as per regulatory requirements, the MPP must be able to reject new account binding requests when the limit is exceeded.

Workflow

For different terminal types of the MPP client, the general account binding workflow is the same. Take the MPP client being an app as an example, the following figure illustrates the account binding workflow when the Alipay+ client SDK is used.

Figure 1. Account binding (App used)

Note: "ACQP" is the abbreviation of "Acquiring Service Provider".

The account binding workflow contains the following steps:

1. The user selects a wallet for account binding. (Step 1)
2. The merchant sends a request to Alipay+, which calls the prepare API to request the authorization URL from the MPP. (Step 2-5)

Note: In scenarios where the user binds the account by scanning the QR code rendered by the merchant based on the authorization URL, the MPP client directly renders the Authorization page in the wallet app for the user to complete account binding. Otherwise, the merchant needs to redirect the user to the Authorization page rendered based on the authorization URL.

3. With the authorization URL, the merchant/ACQP redirects the user to the Authorization page rendered by the MPP. (Step 6)
4. After the user logins to the MPP client (wallet app), the MPP client calls the signContract API of the Alipay+ client SDK to start the contract signing process between the user and MPP. (Step 7-8)
5. The Alipay+ client SDK calls the showAuthPage API to show the authorization page. (Step 9)
6. The MPP client renders and presents the Authorization page, where the user confirms the agreement information. (Step 10-11)
7. The MPP generates the authorization code (authCode), and returns it to the merchant/ACQP in the following two ways at the same time:

• By redirecting the user to the Authorization result page whose URL contains the authorization code. (Step 13-15)
• By calling the authNotify API asynchronously. (Step 16-17)

8. With the authorization code, the merchant calls the applyToken API to request an access token. (Step 18-19)
9. The MPP returns the access token and customer ID to Alipay+. (Step 20-21)
10. The MPP also calls the authNotify API to notify Alipay+ of the access token, and then Alipay+ notifies the merchant/ACQP of the access token. (Step 22-23)
11. The merchant renders and presents the Authorization result page to the user. (Step 24)

Note: For the figure illustration about the account binding workflow of the case where the terminal type of the MPP client is WAP/Web, see Appendix.

MPP actions

The following sections describe the steps that the MPP needs to perform to complete account binding.

Step 1. Provide the authorization URL

Alipay+ sends a request to the MPP to fetch the authorization URL by calling the prepare API. The MPP needs to prepare the authorization URL and then return it to Alipay+ along with the following three parameters: schemeUrl, applinkUrl and normalUrl.

Processing logic

When handling the prepare API requests, the MPP needs to take the following things into consideration:

• Refer to the following tables to handle the request parameters and configure the response parameters properly.

Table 1. Request parameters in the prepare API

Table 2. Response parameters in the prepare API

• It is recommended that the MPP use fields such as the user ID assigned by the MPP, authClientId, scopes, and referenceAgreementId for idempotency control. When handling requests for authorization codes with the same values of these fields, the MPP must return the same values for the required fields.

Sample

Alipay+ sends a request to the MPP.

{
  "acquirerId": "102218800000001234",
  "pspId": "102208800000001234",
  "authClientId": "2188123412341234",
  "authClientName": "Merchant",
  "authClientDisplayName": "Merchant display",
  "referenceMerchantId": "2188123412341230",
  "authRedirectUrl": "https://www.merchant.com/authenticationResult?param1=123&param2=234",
  "scopes": [
    "AGREEMENT_PAY"
  ],
  "customerBelongsTo": "ALIPAY_CN",
  "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
  "terminalType": "APP",
  "referenceAgreementId": "aNDJWQNNabdad1234",
  "osType": "IOS",
  "osVersion": "11.0.2",
  "authNotifyUrl": "https://www.alipayplus.com/authenticationNotify?referenceAgreementId=aNDJWQNNabdad1234"
}

The MPP returns a response to Alipay+.

{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  },
  "applinkUrl": "https://applink.openauth.xxx.com/authentication.htm?authId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3",
  "normalUrl": "https://openauth.xxx.com/authentication.htm?authId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3",
  "schemeUrl": "scheme://cahsierpay?param=1"
}

More information

For more information about how to handle the prepare API request and send the response, see prepare.

Step 2. Render and present the Authorization page

The MPP needs to prepare the authorization page and handle the redirection from the merchant to the MPP wallet.

Prepare the Authorization page

The MPP client needs to render the Authorization page where the user can sign the Auto Debit agreement and complete the authorization.

Depending on the terminal type of the MPP client, the way for the MPP to render the Authorization page is different.

• If the terminal type of the MPP client is App, call the signContract API of the Alipay+ client SDK to complete the contract signing process. For more information about how to use the SDK, see Alipay+ MPP Client SDK.
• If the terminal type of the MPP client is WAP/Web, design and render the Authorization page to display the authorization details such as the merchant name and authorization scopes. For more information about the Authorization page requirements, see the UX design guideline of the Authorization page.

Handle the redirection from the merchant to the wallet

With the authorization URL returned in Step 1, the merchant redirects the user to the Authorization page in the wallet app. It is required that the MPP provide all the following parameters in the authorization URL:

• schemeUrl
• applinkUrl
• normalUrl

For more information about the three parameters, see the preceding Table 2.

For more information about redirection, see Redirection guide between Merchant and Mobile Payment Provider.

Step 3. Generate the authorization code

After the user confirms the authorization, the MPP needs to generate an authorization code at its server side. The following conditions must be met when generating the authorization code:

• The authorization code is within 32 bits in length.
• The prefix of the authorization code is in the format of 281***13, where the *** part is the routing number assigned by Alipay+.
• The authorization code is valid for at least 5 minutes and can be used only once.

Step 4. Redirect the user back to the merchant

After the authorization code is generated at the wallet side, the user needs to be redirected to the Authorization result page at the merchant side. The URL of this page is composed of the following elements:

• the value specified by the authRedirectUrl parameter in the prepare API request.
• the authorization code generated in Step 3.
• the authorization statement specified by the authState parameter in the prepare API request. The value is used by the auth client to prevent cross-site request forgery (CRSF) attacks.

The following example shows a sample URL that is used to redirect the user to the merchant:

https://www.merchant.com/authorizationResult?authCode=281xxx13&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7

Depending on the terminal type of the MPP client, the way of implementing the redirection is different.

• If the terminal type of the MPP client is App, the MPP needs to handle the showAuthPage API request from the Alipay+ client SDK to return the authorization code to the Alipay+ client SDK. The Alipay+ client SDK then composes the URL and redirects the user to the merchant.
• If the terminal type of the MPP client is WAP/Web, the MPP server returns the required elements (authRedirectUrl, authCode, authState) to the MPP client. The MPP client then composes the URL and redirects the user back to the merchant.

To ensure a smooth redirection to the merchant page, the following requirements must be met:

• Trust the URL specified by authRedirectUrl, and complete the redirection without setting a whitelist.
• Support the redirection regardless of whether the authorization fails, succeeds, or is canceled.
• Support the redirection regardless of whether the authRedirectUrl specifies a URL scheme, Universal Link, App Link, or WAP URL.

For more information about the redirection, see Redirection guide between Merchant and Mobile Payment Provider.

Step 5. Notify Alipay+ of the authorization code

To ensure that the authorization code is transmitted to the ACQP side, the MPP needs to call the authNotify API to asynchronously notify Alipay+ of the authorization code.

Processing logic

• When configuring the authNotify API request, the MPP needs to set the authorizationNotifyType parameter to AUTHCODE_CREATED to indicate that the notification is about authorization code creation.
• In certain country/region, per regulatory requirements, when the value of the scopes field in the prepare API request includes USER_LOGIN_ID, the MPP must mask the user login ID to protect sensitive information when configuring the authNotify API requests.

Sample

The MPP sends a request to Alipay+ to notify that the authorization code is created at the wallet side.

{
  "authorizationNotifyType":"AUTHCODE_CREATED",
  "authClientId": "218823863726*********",
  "referenceMerchantId": "218823863726*********",
  "authCode": "281010033AB2F588D14B4323*********",
  "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
  "referenceAgreementId": "aNDJWQNNabdad****"
}

Alipay+ returns a response to the MPP.

{
   "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
   },
  "acquirerId": "102xxxxxxxxxxxx0001",
  "pspId":"102xxxxxxxxxxxx0001"
}

More information

For more information about how to send the authNotify API request and handle the response, see authNotify.

Step 6. Provide the access token

From the redirect URL that is constructed in Step 4, Alipay+ can obtain the authorization code (authCode) and use it in the applyToken API request to apply for an access token. The MPP provides the access token by specifying the accessToken parameter in the response to the applyToken API request. The auth client can then use the access token to access the corresponding user's resources.

The applyToken API can also be used to refresh the access token when the original access token is expired.

Processing logic

When handling the applyToken API requests, the MPP needs to take the following things into consideration:

• Refer to the following tables to handle the request parameters and configure the response parameters properly.

Table 3. Request parameters in the applyToken API

Table 4. Response parameters in the applyToken API

• Additionally, depending on the purpose of the API call, pay attention to the following things accordingly:

• To request an access token:

• An authorization code can be used only once. If the authorization code is used for a second time, the MPP returns a result.resultStatus of F with error code INVALID_AUTHCODE.
• If the access token is valid for a long term, its validity period needs to be at least 10 years. In this case, you do not need to provide a refresh token.
• If the access token is valid for a short term, ensure its validity period is at least 1 year and provide a refresh token, which can be used by the auth client to get a new access token within the refresh token validity period. The refresh token validity period needs to be at least 1.5 years.

• To refresh the access token:

• If the refresh token is invalid, the MPP returns a result.resultStatus of F with error code INVALID_REFRESH_TOKEN.
• If the refresh token is expired, the MPP returns a result.resultStatus of F with error code EXPIRED_REFRESH_TOKEN/INVALID_REFRESH_TOKEN.

Sample

Alipay+ sends a request to the MPP.

{
  "acquirerId":"102218800000000001",
  "pspId":"102208800000000001",
  "authCode": "281010133AB2F588D14B432312345678",
  "grantType": "AUTHORIZATION_CODE"
}

The MPP returns a response to Alipay+.

{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35",
  "accessTokenExpiryTime": "2019-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811",
  "refreshTokenExpiryTime": "2019-06-08T12:12:12+08:00",
  "customerId":"27898089xxxxxxxxxxxxxxxx1",
  "userLoginId":"62-343**736"
}

More information

For more information about how to handle the applyToken API request and send the response, see applyToken.

(Optional) Step 7. Notify Alipay+ of the access token

After the access token is generated at the wallet side, the MPP calls the authNotify API to notify Alipay+ of the access token.

Processing logic

• When configuring the authNotify API request, the MPP needs to set the authorizationNotifyType parameter to TOKEN_CREATED to indicate that the notification is about access token creation.
• In certain country/region, per regulatory requirements, when the value of the scopes field in the prepare API request includes USER_LOGIN_ID, the MPP must mask the user login ID to protect sensitive information when configuring the authNotify API requests.

Sample

The MPP sends a request to Alipay+ to notify that the access token is created at the wallet side.

{
  "authorizationNotifyType":"TOKEN_CREATED",
  "authClientId": "218823863726*********",
  "referenceMerchantId": "218823863726*********",
  "referenceAgreementId": "667d730b56*********",
  "accessToken": "281010033AB2F588D14B4323863726*********",
  "accessTokenExpiryTime": "2021-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC*********",
  "refreshTokenExpiryTime": "2021-06-08T12:12:12+08:00",
  "scopes": ["AGREEMENT_PAYMENT"],
  "customerId":"27898089xxxxxxxxxxxxxxxx1",
  "userLoginId":"62-343**736"
}

Alipay+ returns a response to the MPP.

{
   "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
   },
  "acquirerId": "102xxxxxxxxxxxx0001",
  "pspId":"102xxxxxxxxxxxx0001"
}

More information

For more information about how to send the authNotify API request and handle the response, see authNotify.

Appendix

The following figure illustrates the account binding workflow when the terminal type of the MPP client is WAP/Web.

Figure 2. Account binding workflow (WAP/Web used)