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 Partner (MPP) needs to take to implement account binding by using Alipay+ APIs rather than using the Alipay+ client SDK. In this scenario, the terminal type of the MPP client can be App, WAP, or Web.

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

The following figure illustrates the workflow of account binding by using Alipay+ APIs.

Figure 1. Account binding without client SDK

Note: "ACQP" is the abbreviation of "Acquiring Partner".

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 interface 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 URLs, 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, the MPP client renders and presents the Authorization page, where the user confirms the agreement information. (Step 7-9)
5. The MPP generates the authorization code (authCode), and returns it to the merchant/ACQP in one of the following ways:

• By redirecting the user to the Authorization result page whose URL contains the authorization code. (Step 11-12)
• By calling the authNotify interface asynchronously. (Step 13-14)

6. With the authorization code, the merchant calls the applyToken interface to request an access token. (Step 15-16)
7. The MPP returns the access token and customer ID. (Step 17-18)
8. The MPP also calls the authNotify interface to notify Alipay+ of the access token, and then Alipay+ notifies the merchant/ACQP of the access token. (Step 19-20)
9. The merchant renders and presents the Authorization result page to the user. (Step 21)

MPP actions

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

Step 1. Provide the authorization URLs

Alipay+ sends a request to the MPP to fetch the authorization URL by calling the prepare interface. 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 interface

Table 2. Response parameters in the prepare interface

• 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":"10221880000000****",
  "pspId":"10220880000000****",
  "authClientId": "218812341234****",
  "authClientName": "Merchant",
  "authClientDisplayName": "Merchant display",
  "referenceMerchantId": "218812341234****",
  "authRedirectUrl": "https://www.merchant.com/authenticationResult?param1=123&param2=234",
  "scopes": ["AGREEMENT_PAY"],
  "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
  "terminalType": "APP",
  "referenceAgreementId": "aNDJWQNNabdad****",
  "osType": "IOS",
  "osVersion": "11.0.2",
  "authNotifyUrl": "https://www.alipayplus.com/authenticationNotify?referenceAgreementId=aNDJWQNNabdad****"
}

The MPP returns a response to Alipay+.

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

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. To do this, the MPP needs to manually design and render the Authorization page to display 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 at the wallet side. 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 Partner.

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 10 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

The MPP server needs to return the required elements (authRedirectUrl, authCode, authState) to the MPP client. The MPP client 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 Partner.

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 interface 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 redirection URL that is constructed in Step 4, Alipay+ can obtain the authorization code (authCode) and use it in the applyToken interface to request 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 interface can also be used to refresh the access token when the original access token is expired. For every access token, the MPP must also provide a refresh token, which can be used by the auth client to get a new access token within the refresh token validity period.

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 interface

Table 4. Response parameters in the applyToken interface

• 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 short term, set the validity period to at least one year.

• 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": "663A8FA9D83648EE8AA11FF682989DC7",
  "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 interface 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.