Alipay+ DocsAlipay+ Docs
APIs & SDKs

Account binding

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

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

Ensure that the merchant information is registered before processing account binding. For more information, see Merchant registration.

Workflow

The merchant needs to design the entrance of starting an account binding process. After the user decides to start the process, the merchant and the Acquiring Service Provider need to implement the account binding process as described below.

The following figure illustrates the workflow of account binding.

accountbinding.png

Figure 1. Account binding workflow

The account binding workflow contains the following key steps:

  1. The user chooses to start the account binding process at the merchant side. (Step 1)
  2. The merchant consults available Alipay+-supported wallets from Alipay+ via the Acquiring Service Provider, and displays all the available wallets on the Add payment method page. (Step 2 - 6)
  3. After the user selects one of the Alipay+-supported wallets, the merchant requests the authorization URL from Alipay+ via the Acquiring Service Provider and redirects the user to the returned URL. (Step 7 -12)
  4. After the user signs the authorization agreement, the user is redirected back to the merchant with auth code. Meanwhile, Alipay+ sends a notification that includes the auto code to the Acquiring Service Provider, who then further forwards the notification to the merchant. (Step 13 - 17)
  5. With the received auth code, the merchant initiates the request for the access token via the Acquiring Service Provider. The Acquiring Service Provider calls the applyToken interface from Alipay+, and Alipay+ then returns the access token in the synchronous response and a separate asynchronous notification. (Step 18 - 23)
  6. After the merchant receives the access token from Alipay+ via Acquiring Service Provider, the merchant processes the account binding logic and displays the binding success result to the user. (Step 24 - 25)

Acquiring Service Provider actions

The following section describes the capabilities that the Acquiring Service Provider needs to integrate with Alipay+ for account binding and the service that the Acquiring Service Provider provides to the merchant.

1. Consult the available Alipay+ supported wallets

On behalf of the merchant, the Acquiring Service Provider needs to call the consultPayment interface to get the list of available Alipay+-supported wallets from Alipay+ and return the wallet list to the merchant. Then the merchant needs to render the Add payment method page with the wallet list, where the user can select a specific wallet for further authorization.

The following figure illustrates the consultation process.

consultPayment.png

Figure 2. The workflow of the consultation process

Processing logic

  • The following list provides the key information that the Acquiring Service Provider needs to take into considerations when configuring the request parameters of the consultPayment interface:
    • paymentAmount.currency: specifies the transaction currency, which is then used by Alipay+ as one of the factors to filter out the available wallets. It is also the currency that the auth client will use in the succeeding payment. The value of this parameter must be one of the three-character ISO-4217 currency codes, for example, e.g. USD, GBP, AUD.
    • paymentAmount.value: as this is a consultation for account binding, which means no actual payment occurs, the amount value needs to be set as 0.
    • paymentFactor.isAgreementPayment: set the value as true to specify that the current scenario is Auto Debit.
    • settlementStrategy.settlementCurrency: specify the ISO three-character currency code that the Alipay+ Partner wants to be settled against.
    • (optional) userRegion: specify 2-character country/region code in ISO-3166. The returned wallet list is ordered according to the region information provided in this field.
  • The following table lists the different results that the Acquiring Service Provider might receive from Alipay+.

result.resultStatus

result.resultCode

Actions

S

SUCCESS

The Acquiring Service Provider needs to return the information of all the available Alipay+-supported wallets to the merchant, who then needs to render the Add the payment method page with the wallet logos. The merchant can download the logos from the URLs that are provided by Alipay+.

F

...

The consultation failed at the Alipay+ side. Take actions according to the error message in result.resultCode.

Note: If the result.resultCode parameter is returned as NO_PAY_OPTIONS, there is no available Alipay+ supported wallet retrieved for this account binding process. The merchant needs to remind the user that no available wallets are supported for him/her.

U

...

The Acquiring Service Provider needs to retry the consultPayment request with the same request parameter values until a certain S or F result is received.

No result received

Sample

The Acquiring Service Provider sends a consultPayment request to Alipay+.

copy
{
  "userRegion": "PH",
  "paymentAmount": {
    "currency": "PHP",
    "value": "0"
  }, 
  "paymentFactor": {
    "isAgreementPayment": "true"
  },
  "settlementStrategy": {
    "settlementCurrency": "USD"
  },
  "merchant": {
    "referenceMerchantId": "M00xxxxx0001"
  },
  "env": {
      "terminalType":"APP",
      "OsType":"IOS"
   }
}

Alipay+ returns a response back to the Acquiring Service Provider.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentOptions": [{
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodCategory": "WALLET",
    "enabled": "true",
    "brandName": "Alipay+™ Partner",
    "logo": {
      "logoName": "AlipayPlus",
      "logoUrl": "https://www.alipayplus.com/logo/20022222xxx.png"
    },
    "preferred": "false",
    "paymentOptionDetail": {
      "paymentOptionDetailType": "CONNECT_WALLET",
      "connectWallet": {
        "supportWallets": [
          {
            "walletName": "GCASH",
            "walletBrandName": "Gcash",
            "walletLogo": {
              "logoName":"Gcash",
              "logUrl":"https://www.alipayplus.com/logo/gcash.png"
            },
            "walletRegion": "PH",
            "walletFeature": {
              "supportCodeScan": "true",
              "supportCashierRedirection": "true"
            }
          }
        ]
      }
    }
  }]
}

More information

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

2. Fetch the authorization URL

After the merchant displays all the available Alipay+ supported wallets to the user, and the user selects the wallet he/she wants to bind, the merchant initiates a request to the Acquiring Service Provider for the authorization URL of the selected wallet. The Acquiring Service Provider needs to call the prepare interface from Alipay+ to get the authorization URL information and return it to the merchant.

The following figure illustrates the process of requesting the authorization URL:

FetchAuthorizationURL.png

Figure 3. Requesting Authorization URL process

Processing logic

  • The following list provides the key information that the Acquiring Service Provider needs to take into consideration when configuring the request parameters of the prepare interface:
    • authClientId: specifies the unique id of the auth client to whom the user grants authorization. Normally the auth client refers to the merchant.
    • authClientName: specifies the legal name of the auth client. Normally it is the legal name of the merchant.
    • (optional) authClientDisplayName: specifies the display name of the auth client, which is displayed at the Wallet side. Normally it is the merchant's business name.
    • (optional) authClientLogo: specifies the URL of the auth client's logo. It is provided by the auth client. Normally it is the logo file of the merchant. The logo can be displayed on the authorization page in the wallet if this field is provided.
    • 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 Mobile Payment Provider (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. Versus the URL that is specified on the authRedirectUrl parameter, the complete URL reconstructed 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 generated by the Mobile Payment Provider. 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 format of the complete URL that is constructed based on the authorization redirection URL: https://www.merchant.com/authorizationResult?authCode=281010133AB2F588D14B432312345678&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7

    • customerBelongsTo: specifies the name of the wallet that the customer selects. It must be set to the value of the walletName field that is returned in the response of the consultPayment interface.
    • 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"]. For more information about the authorization scopes that you can use, see the specification of the prepare interface.
    • (optional) referenceAgreementId: specifies the unique ID that is assigned by the auth client to identify the current authorization.
    • (optional) authNotifyUrl: specifies the URL that is used by Alipay+ to notify the Acquiring Service Provider of the authorization information, for example, an auth code or an access token is created. This field is required when the Acquiring Service Provider wants to receive the authorization notification from Alipay+. For security reasons, The URL must use HTTPS instead of HTTP.
    • 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:
    • schemeUrl: The URL scheme that redirects users to open an APP.
    • applinkUrl: 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.
    • normalUrl: The Web/WAP URL that redirects users to a Web/WAP page in the browser or the WebView.
    • appIdentifier: Android package name. Required when the value of the osType parameter is ANDROID.

The Acquiring Service Provider needs to return the information to the merchant, and then the merchant uses the URL information to decide how to evoke the user-selected wallet to proceed with the authorization process.

The merchant needs to trust the URLs returned from Alipay+, and allows the user to be redirected to other apps for proceeding with the further steps at the wallet side.

Note:

    • When result.resultCode is SUCCESS, schemeUrl, applinkUrl, and normalUrl cannot all be null.
    • For priorities of which URL to use for the redirection to the wallet side, schemeUrl > applinkUrl > normalUrl.
    • In some scenarios (for example, when terminalType=WEB/WAP and the terminal cannot handle the schemeUrl or applinkUrl), Alipay+ only returns normalUrl.

For more information about how to process different URLs per different terminal type and os type and how to redirect the user from the merchant side to the wallet side, see Redirection guides between Merchant and Mobile Payment Partner.

  • The following table lists the different results that the Acquiring Service Provider might receive from Alipay+.

result.resultStatus

result.resultCode

Actions

S

SUCCESS

An authorization URL has been returned from A+, the merchant needs to redirect the user to the authorization URL so that the user can proceed with the account binding process.

F

...

The authorization preparation failed at Alipay+ side. Take actions according to the error message in result.resultCode.

U

...

The Acquiring Service Provider needs to retry the prepare request with the same request parameter values until a certain S or F result is received.

No result received

Sample

The Acquiring Service Provider sends a prepare request to Alipay+.

copy
{
    "customerBelongsTo": "ALIPAY_CN",
    "authClientId": "218812341234****",
    "authClientName": "Merchant",
    "authRedirectUrl": "https://www.merchant.com/authenticationResult?param1=123&param2=234",
    "scopes": [
        "AGREEMENT_PAY",
        "USER_LOGIN_ID"
    ],
    "referenceMerchantId":"20397299403****",
    "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
    "terminalType": "APP",
    "referenceAgreementId": "aNDJWQNNabdad****",
    "osType": "ANDROID",
    "osVersion": "6.0.2",
    "authNotifyUrl": "https://www.merchant.com/authenticationNotification"
}

Alipay+ returns a response to the Acquiring Service Provider.

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

More Information

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

3. Retrieve the auth code

After the previous step, the merchant needs to redirect the user to the wallet's authorization page. After the user confirms authorization on the authorization page, the Mobile Payment Provider (wallet) redirects the user to the page of the URL, which consists of the authorization redirection URL (authRedirectUrl), auth code (authCode) and auth statement (authState).

Asynchronously, Alipay+ calls the authNotify interface to send a notification to the URL that the Acquiring Service Provider has specified on the authNotifyUrl parameter of the prepare interface. The notification also contains the auth code. After receiving the notification, the Acquiring Service Provider needs to notify the merchant of the auth code.

The Acquiring Service Provider needs to retrieve the auth code for the succeeding request for an access token.

Notes:

  • It is strongly recommended that the Acquiring Service Provider integrate the authNotfify API to ensure the 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 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 authNotfify 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 fron 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. The Acquiring Service Provider needs to use a separate notification to notify the merchant of the auth code after receiving it from Alipay+.

The following figure illustrates the process of retrieving the auth code:

GetAuthCode.png

Figure 4. Workflow of retrieving the auth code

Processing logic

  • The following list provides the key information that the Acquiring Service Provider needs to take into consideration when handling the request parameters of the authNotify interface:
    • authorizationNotifyType: as the notification is sent out to notify the Acquiring Service Provider of the auth code, the value is set as AUTHCODE_CREATED.
    • authCode: used by confidential and public clients to exchange for an access token. This field is only available when authorizationNotifyType is set as AUTHCODE_CREATED.
      • When both the authNotify interface and the authorization redirection URL provide the authCode, the one from the authorization redirection URL is preferred.
      • When only the authNotify interface provides the authCode, the Acquiring Service Provider must decide whether or not to use the authCode to call the applyToken interface. This is because that if the authorization redirection fails and the Acquiring Service Provider completes the accounting binding by using the authCode from the authNotify interface, there can be no redirect-back page to tell the user of the account binding result.
    • authState: specifies the authorization statement. The value is consistent with the one that is specified on the authState parameter of the prepare request. This field is only available when authorizationNotifyType is set as AUTHCODE_CREATED.
    • customerId: The unique ID that is assigned by the wallet to identify a customer. The field is available when the authorization is successful.
  • After the Acquiring Service Provider successfully handles the notification request, the Acquiring Service Provider needs to return a response to Alipay+. Alipay+ provides a notification retry mechanism if the result.resultCode parameter in the notification response returned from the Acquiring Service Provider is not S. For more information about how to handle the notification, see Handle notification.

Sample

Alipay+ sends an authNotify request to the Acquiring Service Provider.

copy
{
  "authorizationNotifyType":"AUTHCODE_CREATED",
  "authClientId": "218823863726*********",
  "referenceMerchantId": "218823863726*********",
  "authCode": "281010133AB2F588D14B43231234****",
  "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
  "referenceAgreementId": "aNDJWQNNabdad****",
  "acquirerId": "102xxxxxxxxxxxx0001",
  "pspId":"102xxxxxxxxxxxx0001"
}

The Acquiring Service Provider returns a response to Alipay+.

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    }
}

More information

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

4. Request the access token

On behalf of the merchant, the Acquiring Service Provider calls the applyToken interface to request an access token from Alipay+ with the auth code that is retrieved in Step 3. After receiving the access token from the Acquiring Service Provider, the merchant then binds the access token with the user account and renders the binding success result. The access token is also used by the merchant to initiate a payment via the Acquiring Service Provider.

The Acquiring Service Provider 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 interface after processing the applyToken request. Integration of the authNotify API is optional but recommended.

The following figure illustrates the process of requesting an access token:

GetAccessToken.png

Figure 5. Flow to use authCode to retrieve accessToken from Alipay+

Processing logic

applyToken

  • The following list provides the key information that the Acquiring Service Provider needs to take into consideration when configuring the request parameters of the applyToken interface to obtain an access token:
    • 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 table lists the different results that the Acquiring Service Provider might receive from Alipay+.

result.resultStatus

result.resultCode

Actions

S

SUCCESS

The access token has been generated by Alipay+ successfully. The Acquiring Service Provider sends the access token to the merchant, who then proceeds to the next action.

F

...

The access token application failed. The Acquiring Service Provider syncs the result with the merchant, and the merchant needs to guide the user to restart the account binding process.

U

...

The result of the access token application is unknown. The Acquiring Service Provider syncs the result with the merchant and waits for the authorization notification from Alipay+. The merchant can either wait for the authorization notification from Alipay+ via the Acquiring Service Provider, or guide the user to restart the account binding process.

No result received

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, the merchant needs to reinitiate the account binding process.

authNotify

  • The following list provides the key information that the Acquiring Service Provider needs to take into consideration when handling the request parameters of the authNotify interface:
    • authorizationNotifyType: as the notification is sent out to notify the Acquiring Service Provider of the access token, the value is set as TOKEN_CREATED.
    • accessToken: specifies the access token from Alipay+, which is used by the auth client to initiate a payment against the user.
      • When both the applyToken interface and the authNotify interface provide the accessToken, the one from the applyToken interface is preferred.
    • accessTokenExpiryTime: specifies the expiration time of the access token, after which the auth client cannot use this access token to deduct funds from the user's account.
    • refreshToken: used by the auth client to request a new access token when the current access token expires. With this field, a valid access token can be obtained continuously without any further interaction with the user.
    • refreshTokenExpiryTime: the expiration time of the refresh token, after which the auth client cannot use this token to retrieve a new access token.
  • After the Acquiring Service Provider successfully handles the notification request, the Acquiring Partner needs to return a response to Alipay+. Alipay+ provides a notification retry mechanism if the result.resultCode parameter in the notification response returned from the Acquiring Service Provider is not S. For more information about how to handle the notification, see Handle notification.

The Acquiring Service Provider also needs to sync the notification with the merchant.

Sample

The Acquiring Service Provider sends an applyToken request to Alipay+.

copy
{
    "authClientId": "218xxxxxxxxx1234",
    "grantType": "AUTHORIZATION_CODE",
    "authCode": "281010133AB2F588D14B43231234****"
}

Alipay+ returns a response to the Acquiring Service Provider.

copy
{
    "acquirerId": "102xxxxxxxxxxx0001",
    "pspId": "102xxxxxxxxxxx0001",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    },
    "accessToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAF35",
    "accessTokenExpiryTime": "2019-06-06T12:12:12+08:00",
    "refreshToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7811",
    "refreshTokenExpiryTime": "2019-06-08T12:12:12+08:00",
    "customerId": "27898089xxxxxxxxxxxxxxxx1",
    "userLoginId": "138******27"
}

Alipay+ sends an authNotify request to the Acquiring Service Provider.

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","USER_LOGIN_ID"],
  "customerId":"27898089xxxxxxxxxxxxxxxx1",
  "userLoginId":"62-343**736",
  "acquirerId": "102xxxxxxxxxxxx0001",
  "pspId":"102xxxxxxxxxxxx0001"
}

The Acquiring Service Provider returns a response to Alipay+.

copy
{
   "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
   }
}

More information

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

5. Refresh the accessToken

Before the original access token expires, or for some security reason, the merchant wants to deactivate the existing access token and get a new access token for the same authorization. To achieve this goal, the Acquiring Service Provider needs to call the applyToken interface with the refresh token and returns a pair of a new access token and refresh token that is returned from Alipay+ to the merchant."

The following figure illustrates the refreshing accessToken process:

RefreshToken.png

Figure 6. Refresh accessToken flow

Processing logic

  • The following list provides the key information that the Acquiring Service Provider needs to take into consideration when configuring the request parameters of the applyToken interface to refresh the access token:
    • authClientId: the unique identifier for the auth client. Normally it is a unique ID for the merchant.
    • grantType: to refresh an access token with the refresh token, set the grant type as REFRESH_TOKEN.
    • refreshToken: specifies the refresh token that is retrieved from the response of the applyToken API call in Step 4.
  • The following table lists the different results that the Acquiring Service Provider might receive from Alipay+.

result.resultStatus

result.resultCode

Actions

S

SUCCESS

A new access token has been generated by Alipay+ successfully. The Acquiring Service Provider sends the access token to the merchant, who then proceeds to the next action.

F

...

The access token application failed. Take actions according to the error message in result.resultCode.

U

...

The result of the access token application is unknown. The Acquiring Service Provider syncs the result with the merchant and waits for the authorization notification from Alipay+. The merchant can either wait for the authorization notification from Alipay+ via the Acquiring Service Provider or retry the same request again.

No result received

  • When an access token and refresh token are generated, the accessTokenExpiryTime and refreshTokenExpiryTime parameters are also specified by Alipay+ and returned to the merchant. The merchant needs to set up the token refresh process, which ensures that the token refresh process is initiated before the original access token expired.
  • The expiry period is defined by the Mobile Payment Partner. Different Mobile Payment Partners might have different requirements of the expiry period.

Sample

The Acquiring Service Provider sends an applyToken request to Alipay+ to refresh the access token.

copy
{
    "authClientId": "218xxxxxxxxx1234",
    "grantType": "REFRESH_TOKEN",
    "refreshToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7811"
}

Alipay+ returns a response to the Acquiring Service Provider.

copy
{
    "acquirerId": "102xxxxxxxxxxx0001",
    "pspId": "102xxxxxxxxxxx0001",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    },
    "accessToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAF35",
    "accessTokenExpiryTime": "2019-06-06T12:12:12+08:00",
    "refreshToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7811",
    "refreshTokenExpiryTime": "2019-06-08T12:12:12+08:00",
    "customerId": "27898089xxxxxxxxxxxxxxxx1",
    "userLoginId": "138******27"
}

More Information

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