Alipay+Alipay+

Account binding with client SDK

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 the Alipay+ client SDK. In this scenario, the terminal type of the MPP client must be App.

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 the Alipay+ client SDK.

Auto SDK.jpg

Figure 1. Account binding with 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.

  1. With the authorization URL, the merchant/ACQP redirects the user to the Authorization page rendered by the MPP. (Step 6)
  2. After the user logins to the MPP client (wallet app), the MPP client calls the signContract interface by using the Alipay+ client SDK to start the contract signing process between the user and MPP. (Step 7-8)
  3. The Alipay+ client SDK calls the getAuthCode service to request an authorization code. (Step 9)
  4. The MPP client renders and presents the Authorization page, where the user confirms the agreement information. (Step 10-11)
  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 13-15)
    • By calling the authNotify interface asynchronously. (Step 16-17)
  1. With the authorization code, the merchant calls the applyToken interface to request an access token. (Step 18-19)
  2. The MPP returns the access token and customer ID to Alipay+. (Step 20-21)
  3. 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 22-23)
  4. The merchant renders and presents the Authorization result page to the user. (Step 24)

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

No .

Field

Remarks

1

pspId

/

2

acquirerId

/

3

authClientId

/

4

authClientName

Optional

/

5

authClientLogo

Optional

/

6

authClientDisplayName

The display name of the auth client, usually the business name of the merchant.

7

authRedirectUrl

Optional

The redirect URL after authorization. The domain name of the URL is provided by the auth client.

After the user confirms the authorization, the MPP composes the URL and redirects the user to the auth client. For more information about how to compose the URL, see Step 4.

8

customerBelongsTo

/

9

scopes

The authorization scopes. Valid values are:

  • BASE_USER_INFO
  • USER_LOGIN_ID
  • HASH_USER_LOGIN_ID
  • AGREEMNET_PAY
  • SEND_OTP

10

authState

/

11

terminalType

/

12

referenceAgreementId 

This parameter is recommended for idempotency control.

13

osType

Optional

This parameter is required when terminalType is APP or WAP.

14

osVersion

Optional

/

15

authNotifyUrl

The URL specified by this parameter must be in the HTTPS format. The MPP needs to trust the URL without setting a whitelist.

16

referenceMerchantId

/

17

userAgent 

Optional

/

18

passThroughInfo 

Optional

/

Table 2. Response parameters in the prepare interface

No.

Field

Remarks

1

pspId

Optional

/

2

acquirerId

Optional

/

3

result

  • If the value of result.resultStatus is U, the ACQP can try again.
  • If the value of result.resultStatus is F, the prepare API request fails, which might be caused by system defects or failures. It is recommended that the MPP check for exceptions.

4

schemeUrl

Optional

The URL scheme that redirects users to open an app. This field corresponds to the URL scheme for Android and iOS systems.

Note: Required when result.resultCode is SUCCESS.

5

applinkUrl

Optional

The URL that redirects users to open an app, or, if no app is installed, to a WAP page. For Android, this field is the native App Link, and for iOS, the Universal Link.

Note: Required when result.resultCode is SUCCESS.

6

normalUrl

Optional

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

Note: Required when result.resultCode is SUCCESS.

7

passThroughInfo

Optional

/

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

copy
{
  "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+.

copy
{
  "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 call the signContract interface provided by the Alipay+ client SDK to complete the contract signing process. For more information about how to use the SDK, see Alipay+ Client SDK Integration Guide.

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

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

The MPP needs to handle the getAuthCode SPI request from the Alipay+ client SDK to return the authorization code to the Alipay+ client SDK. The Alipay+ client SDK composes the URL and redirects the user 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.

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

Alipay+ returns a response to the MPP.

copy
{
   "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 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

No.

Field

Remarks

1

pspId

/

2

acquirerId

/

3

grantType

  • Specify the value as AUTHORIZATION_CODE to request an access token.
  • Specify the value as REFRESH_TOKEN to refresh the access token.

4

authCode

Specify the authorization code provided by the MPP.

5

refreshToken

Optional

Required when grantType is REFRESH_TOKEN. This parameter can be used for idempotency control. When handling requests for new access tokens with the same refreshToken, the MPP must return the same values for the required fields.

6

passThroughInfo

Optional

/

Table 4. Response parameters in the applyToken interface

No.

Field

Remarks

1

result

If result.resultStatus is F or U, the auth client can guide the user to try again.

2

accessToken

Optional

Required when the request for access token is successful. The value must be within 128 bits in length.

3

accessTokenExpiryTime

Optional

Required when the request for access token is successful.

4

refreshToken

Optional

Required when the request for access token is successful. The value must be within 128 bits in length.

5

refreshTokenExpiryTime

Optional

Required when the request for access token is successful.

6

customerId

Optional

Required when the the access token application request is successful.

7

userLoginId

Optional

  • Required when the value of result.resultCode is SUCCESS 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 when handling the applyToken API requests.

8

passThroughInfo

Optional

/

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

copy
{
  "acquirerId":"102218800000000001",
  "pspId":"102208800000000001",
  "authCode": "663A8FA9D83648EE8AA11FF682989DC7",
  "grantType": "AUTHORIZATION_CODE"
}

The MPP returns a response to Alipay+.

copy
{
  "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.

copy
{
  "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.

copy
{
   "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.