Bind the user account

To enable a merchant to obtain user authorization for deducting funds from a Mobile Payment Partner (MPP) account, you (the MPP) must take the following integration steps to enable the user to bind the MPP account with the merchant account:

• Step 1. Provide the Authorization Confirmation Page info
• Step 2. Render the Authorization Confirmation page
• Step 3. Provide the authorization code
• Step 4. Redirect the user back to the merchant
• Step 5. Provide the access token

Before you begin

After a user initiates account binding at the merchant side, the user is redirected to the MPP client to confirm the authorization. Depending on the terminal type of your client (app, WAP, or Web) and the user experience to be provided, you need to adopt the corresponding integration method.

Before you begin to implement account binding, refer to the following table to determine your integration method.

About the task

The account binding workflow is similar for different terminal types of the MPP client. This topic mainly focuses on the account binding workflow where the user is redirected to the MPP app after initiating account binding on the merchant side and you choose to integrate the Alipay+ client SDK.

Refer to the following figure to learn about the workflow.

Figure 1. Workflow of account binding via MPP app

The workflow contains the following steps:

Note: If the MPP app does not integrate the Alipay+ Client SDK, steps 10, 11, and 16 are skipped. In this case, merchants such as Apple and Google are not supported unless the MPP modifies its app to implement the functions provided by the Alipay+ Client SDK.

1. To add a payment method, the user selects an MPP for account binding. (Step 1)

2. The merchant/Acquiring Partner (ACQP) sends a request to Alipay+, which calls the prepare API to request the Authorization Confirmation page information from the MPP server. (Step 2-3)
3. The MPP server returns the Authorization Confirmation page information to Alipay+, which then syncs the information to the merchant/ACQP. (Step 4-5)
4. The merchant/ACQP navigates the user to the Authorization Confirmation page through either of the following methods:

• If the terminal type of the merchant client is app, the merchant app directly opens the authorization URL to redirect the user to the MPP app. Then, the user logs in to open the Authorization Confirmation page. (Step 6-7)
• If the terminal type of the merchant client is Web, the merchant renders the authorization QR code on a Web page. Then, the user scans the QR code to open the Authorization Confirmation page in the MPP app. (Step 8-9)

5. The MPP app calls the signContract API of Alipay+ Client SDK to start the contract signing process between the user and MPP. Then, Alipay+ Client SDK calls the showAuthPage API to trigger the MPP app to render the Authorization Confirmation page. (Step 10-11)
6. The MPP app renders the Authorization Confirmation page, where the user confirms the agreement information. (Step 12-13)
7. The MPP server generates the authorization code (Step 14).
8. The MPP returns the authorization code to the merchant/ACQP in the following two ways at the same time:

• The MPP server returns the authorization code to the MPP app, which syncs the authorization code to Alipay+ Client SDK. Alipay+ Client SDK redirects the user to the Authorization Result page whose URL contains the authorization code. (Step 15-17)
• The MPP server calls the authNotify API asynchronously to notify Alipay+ of the authorization code. Alipay+ then syncs the authorization code to the merchant/ACQP. (Step 18-19)

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

In addition, see the following documents for more information:

• For the account binding workflow where the user is redirected to the MPP Web or WAP page after initiating account binding on the merchant side, see Workflow of account binding via MPP WAP/Web.
• For a comparison of the integration steps between different terminal types of the MPP client, see Comparison of integration steps between MPP terminal types.

Step 1. Provide the Authorization Confirmation page info

Alipay+ sends a request to the MPP to fetch the Authorization Confirmation page information by calling the prepare API. In response to the prepare API, the MPP needs to return an authorization URL and an authorization QR code to Alipay+.

With the authorization URL, the user can be redirected to the Authorization Confirmation page directly in the MPP app. With the authorization QR code, the merchant can render the authorization QR code on its Web page, and the user can scan the QR code with the MPP app to open the Authorization Confirmation page.

Processing logic

When handling the prepare API request, take the following things into consideration:

• Handle the request properly, especially the following parameters:

• authRedirectUrl: The authorization redirection URL, of which the domain name is provided by the auth client. After receiving the value of this parameter, the MPP must append authCode and authState to it and reconstruct a complete URL that redirects the user back to the merchant when the user completes the authorization process at the wallet side. For more information about how to compose the complete redirection URL, see Step 4.
• scopes: The authorization scopes, which represent what resources or capabilities are authorized to the merchant.
• authNotifyUrl: The MPP must send authorization notification to this URL and trust the URL without setting a whitelist.
• authClientId and referenceAgreementId: These two parameters are jointly used for idempotency control. For requests that are initiated with the same authClientId and referenceAgreementId, the MPP must return the same result.

• Ensure the following parameters are configured properly in the response:

• schemeUrl, applinkUrl, and normalUrl: specifies three different authorization URLs in all of the three parameters to adapt to different redirection scenarios.
• codeValue: specifies the QR code that the user scans to open the Authorization Confirmation page in the MPP app.

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"
  },
  "codeValue": "https://qr.alipayplus.com/aps/long/qwxe9x",
  "codeExpireTime": "2019-06-01T12:01:01+08:30",
  "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://cashierpay?param=1"
}

More information

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

Step 2. Render the Authorization Confirmation page

With the Authorization Confirmation page info obtained in Step 1, the merchant navigates the user to the Authorization Confirmation page through either of the following methods:

• Method 1: If the terminal type of the merchant client is APP, the merchant app directly opens the authorization URL to redirect the user to the MPP app. Then, the user logs in to open the Authorization Confirmation page.
• Method 2: If the terminal type of the merchant client is Web, the merchant renders the authorization QR code on a Web page. Then, the user scans the QR code to open the Authorization Confirmation page in the MPP app.

To prepare the Authorization Confirmation page, the MPP app needs to call the signContract API of Alipay+ Client SDK to start the contract signing process. Alipay+ Client SDK then calls the showAuthPage API to trigger the MPP app to render the Authorization Confirmation page.

For more information about the SDK, see Alipay+ MPP Client SDK.

Besides, if Method 1 is used, the MPP needs to handle the redirection from the merchant to the MPP app. For more information about redirection, see Redirection guide between Merchant and Mobile Payment Provider.

For more information about how to render the Authorization Confirmation page when the terminal type of the MPP client is Web, WAP, or App without SDK, see Comparison of integration steps between MPP terminal types.

Step 3. Provide the authorization code

After the user confirms authorization on the Authorization Confirmation page, the MPP needs to generate an authorization code at the server side. The authorization code needs to meet the following conditions:

• 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.

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. For more information about how to call the authNotify API, see Send authorization notification.

(Conditional) Step 4. Redirect the user back to the merchant

If the user is redirected to the Authorization Confirmation page through the authorization URL, after the authorization code is generated at the MPP side, the MPP needs to redirect the user back to the Authorization Result page at the merchant side.

Note: If the user scans a QR code rendered on the merchant Web page to open the Authorization Confirmation page, the MPP app does not need to redirect the user back to the merchant after the user confirms the authorization.

To enable the redirection, the MPP needs to complete the following steps:

• 1. Compose the URL of the Authorization Result page
• 2. Redirect the user back to the merchant

1. Compose the URL of the Authorization Result page

The URL of the Authorization Result page consists 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 merchant 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

2. Redirect the user back to the merchant

The MPP server returns the required elements (authRedirectUrl, authCode, authState) to the MPP app, which needs to handle the showAuthPage API request from Alipay+ Client SDK to pass the elements to Alipay+ Client SDK. Alipay+ Client SDK then composes the URL and redirects the user to the merchant.

To ensure a smooth redirection to the merchant side, the MPP needs to:

• Trust the URL specified by the authRedirectUrl parameter, 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 parameter 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.

For more information about how to redirect the user back to the merchant when the terminal type of the MPP client is Web, WAP, or App without SDK, see Comparison of integration steps between MPP terminal types.

Step 5. Provide the access token

From the redirection URL that is constructed in Step 4 or the authNotify API request, Alipay+ obtains the authorization code (authCode) and specifies it in the applyToken API request to apply for an access token. The MPP needs to provide the access token by configuring the accessToken parameter in the response. The merchant can then use the access token to access the user's resources.

Note: The applyToken API can also be used to refresh the access token when the original access token is about to expire or has expired. For more information, see Refresh the access token.

Processing logic

When handling the applyToken API request, take the following things into consideration:

• Handle the request properly, especially the following parameters:

• grantType: When Alipay+ uses the authorization code to apply for a new access token, the value of this parameter is set as AUTHORIZATION_CODE.
• authCode: The authorization code that is generated by the MPP in Step 3.

• Ensure the following parameters are configured properly in the response:

• result.resultStatus:

• Each authorization code can be used once only. If an authorization code is used for a second time, the MPP needs to return a result.resultStatus of F with error code INVALID_AUTHCODE.

• userLoginId: Return this parameter if the request is successful and the scopes parameter in the prepare API request contains USER_LOGIN_ID. In certain country/region, per regulatory requirements, the MPP must mask the user login ID to protect sensitive information.
• accessToken and refreshToken:

• The MPP needs to specify the validity periods of accessToken and refreshToken differently based on the value of the scopes parameter in the prepare API, as shown in the following table:

Table 1. Validity periods of accessToken and refreshToken by different scopes

Notes:

• If a business has more than one merchant account, the MPP must allow one MPP account to be bound with multiple merchant accounts.
• In certain country/region, the number of merchant accounts that can be bound with one MPP account is limited as per regulatory requirements. When the limit is exceeded:

• the MPP must be able to reject new requests for access tokens;
• it is recommended that the MPP notify the user of the limit.

Sample

Alipay+ sends a request to the MPP to request an access token.

{
  "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": "2022-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811",
  "refreshTokenExpiryTime": "2022-06-08T12:12:12+08:00",
  "customerId":"2789808900000000000000001",
  "userLoginId":"62-***2736"
}

More information

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

Besides, after the access token is generated, it is recommended that you call the authNotify API to notify Alipay+ of the access token.

For more information about how to call the authNotify API, see Send authorization notification.

More information

Workflow of account binding via MPP WAP/Web

The following figure illustrates the account binding workflow where the user is redirected to the MPP Web or WAP page after initiating account binding at the merchant side.

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

Note:

• The preceding figure illustrates the scenario where the user logs in to bind the account.
• In scenarios where the user scans a QR code to bind the account, the MPP needs to render the QR code on a Web page and implement the following logic:

1. After the user scans the QR code, the MPP app directly renders the Authorization Confirmation page.
2. After the user completes the authorization in the MPP app, the MPP app does not need to redirect the user back to the merchant. However, the MPP Web page needs to redirect the user back to the Authorization Result page at the merchant side.

The account binding workflow contains the following steps:

1. To add a payment method, the user selects an MPP for account binding. (Step 1)
2. The merchant/ACQP sends a request to Alipay+, which calls the prepare API to request the Authorization Confirmation page information from the MPP server. (Step 2-3)
3. The MPP server returns the Authorization Confirmation page information to Alipay+, which then syncs the information to the merchant/ACQP. (Step 4-5)
4. With the authorization URL, the merchant/ACQP redirects the user to the Authorization Confirmation page rendered by the MPP client. (Step 6)
5. After the user logs in to the MPP client, the MPP client renders the Authorization Confirmation page, where the user confirms the agreement information. (Step 7-9)
6. The MPP server generates the authorization code. (Step 10)
7. The MPP returns the authorization code to the merchant/ACQP in the following two ways at the same time:

• The MPP server returns the authorization code to the MPP client, which redirects the user to the Authorization Result page whose URL contains the authorization code. (Step 11)
• The MPP server calls the authNotify API asynchronously to notify Alipay+ of the authorization code. Alipay+ then syncs the authorization code to the merchant/ACQP. (Step 12-13)

8. With the authorization code, the merchant calls Alipay+ to request an access token. Alipay+ calls the applyToken API to request an access token from the MPP server. (Step 14-15)
9. The MPP server returns the access token and customer ID to Alipay+. (Step 16-17)
10. The MPP server also calls the authNotify API to notify Alipay+ of the access token. Alipay+ then notifies the merchant/ACQP of the access token. (Step 18-19)
11. The merchant/ACQP renders the Authorization Result page and displays the authorization result to the user. (Step 20)

Comparison of integration steps between MPP terminal types

The following table compares the integration steps between different terminal types of the MPP client:

Table 2. Comparison of integration steps between different MPP client types