# Bind the user account

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

To enable account binding, the Acquiring Service Provider (ACQP) must complete the following integration steps so that the user can bind their wallet account to their merchant account.

-   [Step 1. Initiate account binding](#K8nqQ)
-   [Step 2. Retrieve the auth code](#9ba53779)
-   [Step 3. Request the access token](#3VKoW)

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](https://docs.alipayplus.com/alipayplus/alipayplus/registration_acq/register_a_merchant.md?role=ACQP&product=Payment1&version=1.4.7).

Different ACQPs provide different service modes, for example:

-   Some ACQPs provide both client-side and server-side capabilities as an integrated service.
-   Some ACQPs provide only server-side capabilities, and require merchants to integrate directly with the Alipay+ client side.

Therefore, for the convenience of developers reading this document, no matter which service mode is used, "your client side" and "your server side" are used uniformly to refer to the corresponding client side and server side in different service modes.

# 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 ACQP need to implement the account binding process as described below.

The following figure illustrates the workflow of account binding.

![Auto debit-Account binding.jpg](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1754040698410-367dd11c-f951-4e0c-9cd2-c5e4ea785160.jpeg)

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.  After the user selects one of the Alipay+-supported wallets, the merchant requests the authorization URL from Alipay+ via the ACQP and redirects the user to the returned URL. (Step 2 -7)
3.  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 ACQP, who then further forwards the notification to the merchant. (Step 8 - 13)
4.  With the received auth code, the merchant initiates the request for the access token via the ACQP. The ACQP calls the **applyToken** API from Alipay+, and Alipay+ then returns the access token in the synchronous response and a separate asynchronous notification. (Step 14 - 20)
5.  After the merchant receives the access token from Alipay+ via ACQP, the merchant processes the account binding logic and displays the binding success result to the user. (Step 21 - 22)

> **Note**: To obtain available wallet information, you can:
>
> -   Call the **consultPayment** API to receive information about payment methods, including wallet logos.
> -   Call the **inquiryRegistrationStatus** API to retrieve the merchant registration result. For Alipay+ brand logo images, use the [Acceptance Mark Generator](../brand_guidelines_acq/brand_online_acq#quwEA) to download the approved assets. For the correct brand name text, refer to the [Brand name list](../brand_guidelines_acq/brand_online_acq#aEESn).

# Step 1. Initiate account binding

The ACQP needs to call the **prepare** API to get the authorization URL information from Alipay+ and return it to the merchant.

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

![FetchAuthorizationURL.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1630260950310-d61b35bb-097a-4cf3-beb5-185db2b90c1e.png)

Figure 2. Requesting Authorization URL process

## Processing logic

-   The following list provides the key information that the ACQP needs to take into consideration when configuring the request parameters of the **prepare** API:

-   _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](#9ba53779).
-   _authState:_ the auth statement that is specified on the _authState_ parameter of the [**prepare**](../api_acq_tile/prepare) API. 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](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**](../api_acq_tile/consult_payment) API.
-   _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** API.
-   **(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 ACQP of the authorization information, for example, an auth code or an access token is created. This field is required when the ACQP 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:

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


-   The following table lists the different results that the ACQP 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` | Multiple possible values exist, such as `ACCESS_DENIED` and `KEY_NOT_FOUND`. | The authorization preparation failed at Alipay+ side. Take actions according to the error message in _result.resultCode._ |
| `U` | Multiple possible values exist, such as `UNKNOWN_EXCEPTION` and `REQUEST_TRAFFIC_EXCEED_LIMIT`. | The ACQP needs to retry the **prepare** request with the same request parameter values until a certain S or F result is received. |
| No result received | No result received | The ACQP needs to retry the **prepare** request with the same request parameter values until a certain S or F result is received. |

## Sample

The ACQP sends a **prepare** request to Alipay+.

```json
{
    "paymentAmount": {
        "currency": "JPY",
        "value": "100"
    },
    "settlementStrategy": {
        "settlementCurrency": "JPY"
    },
    "userRegion": "JP",
    "authClientId": "2188123412341234",
    "authClientName": "Merchant",
    "authClientDisplayName": "Merchant display",
    "referenceMerchantId": "2188123412341230",
    "authRedirectUrl": "https://www.merchant.com/authenticationResult?param1=123&param2=234",
    "scopes": [
        "AGREEMENT_PAY"
    ],
    "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
    "terminalType": "WEB",
    "referenceAgreementId": "aNDJWQNNabdad1234",
    "osType": "IOS",
    "osVersion": "11.0.2",
    "authNotifyUrl": "https://www.merchant.com/authenticationNotify?referenceAgreementId=aNDJWQNNabdad1234"
}
```

Alipay+ returns a response to the ACQP.

```json
{
    "acquirerId": "102218800000001234",
    "pspId": "102208800000001230",
    "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 API (such as the field description and format), see the [**prepare**](../api_acq_tile/prepare) API.

# Step 2. Retrieve the auth code

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

![GetAuthCode.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1630261080785-74a18aad-153a-4a7d-9103-5c878915387e.png)

Figure 3. Workflow of retrieving 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** API to send a notification to the URL that the ACQP has specified on the _authNotifyUrl_ parameter of the **prepare** API. The notification also contains the auth code. After receiving the notification, the ACQP needs to notify the merchant of the auth code.

For more information about how to handle the **authNotify** request and return a response, see [Receive authorization notification](receive_authorization_notification).

You need to retrieve the auth code for the succeeding request for an access token as follows:

-   If both the **authNotify** API and the authorization redirection URL provide the _authCode_, the one from the authorization redirection URL is preferred.
-   If only the **authNotify** API provides the _authCode_, you must decide whether to use that code to call the **applyToken** API. This is because If redirection back to your client side fails and account binding is completed using the _authCode_ from the **authNotify** API, there will be no redirect-back page to inform the user of the account binding result.

> **Notes**:
>
> -   It is strongly recommended that the ACQP integrate the **authNotify** 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 **authNotify** 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 ACQP needs to use a separate notification to notify the merchant of the auth code after receiving it from Alipay+.

# Step 3. Request the access token

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

![GetAccessToken.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1630261199318-9ae4b2c6-604d-42f3-b6d2-e2c1a0394ae0.png)

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

On behalf of the merchant, the ACQP calls the **applyToken** API to request an access token from Alipay+ with the auth code that is retrieved in [Step 2](#9ba53779). After receiving the access token from the ACQP, 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 ACQP.

The ACQP 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** API after processing the **applyToken** request. Integration of the **authNotify** API is optional but recommended.

> **Note**: If both the **applyToken** response and the **authNotify** request provide the _accessToken_, the one from the **applyToken** response is preferred.

## 3.1. Integrate the applyToken API

Your server side needs to integrate the **applyToken** API provided by Alipay+ to request the access token.

### Processing logic

-   The following list provides the key information that the ACQP needs to take into consideration when configuring the request parameters of the **applyToken** API 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 ACQP might receive from Alipay+.

| **result.resultStatus** | **result.resultCode** | **Actions** |
| --- | --- | --- |
| `S` | `SUCCESS` | The access token has been generated by Alipay+ successfully. The ACQP sends the access token to the merchant, who then proceeds to the next action. |
| `F` | Multiple possible values exist, such as `ACCESS_DENIED` and `KEY_NOT_FOUND`. | The access token application failed. The ACQP syncs the result with the merchant, and the merchant needs to guide the user to restart the account binding process. |
| `U` | Multiple possible values exist, such as `UNKNOWN_EXCEPTION` and `REQUEST_TRAFFIC_EXCEED_LIMIT`. | The result of the access token application is unknown. The ACQP 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 ACQP, or guide the user to restart the account binding process. |
| No result received | No result received | The result of the access token application is unknown. The ACQP 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 ACQP, or guide the user to restart the account binding process. |

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

### Sample

The ACQP sends an **applyToken** request to Alipay+.

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

Alipay+ returns a response to the ACQP.

```json
{
    "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"
}
```

For more information about how to use the **applyToken** API (such as the field description and format), see the [**applyToken**](../api_acq_tile/apply_token) API.

## 3.2. Handle the authNotify request

After processing the **applyToken** request successfully, Alipay+ asynchronously calls the **authNotify** API to send a notification to the URL that you specified in the _authNotifyUrl_ parameter of the **prepare** request. The notification also contains the access token. After receiving the notification, your server side needs to notify your client side of the access token.

For more information about how to handle the **authNotify** request and return a response, see [Receive authorization notification](receive_authorization_notification).