This chapter goes through the process of integrating the capability of accepting payments by using Alipay+ server SDK, Alipay+ client SDK, and APIs. This process is only applicable when the terminal type of the MPP client is App.

The following two scenarios are supported:

• After the user places an order, the merchant redirects the user to the MPP's wallet app to complete the payment.
• After placing an order, the user uses the MPP's wallet app to scan the order code for the payment.

Workflow

To accept a payment, the MPP must identify whether the code is an Alipay+ code, then decode the code value before proceeding to the payment processes.

The following figure illustrates the payment flow:

Figure 1. Payment flow

The payment flow consists of the following steps:

1. The user chooses a payment method and the merchant/ACQP redirects the user to the cashier page with the code value (step 1-2).
2. The MPP client sends the code value to the MPP server for identification (step 3).
3. The MPP server identifies the code.

• If the code is an MPP local code or in the MPP's allowlist, the MPP identifies the code according to its own business logic. For more information about what is an allowlist, see Allowlist solution.
• If the code is neither an MPP local code nor in the MPP allowlist, the MPP server calls Alipay+ server SDK to identify the code (step 4).

4. The MPP server/Alipay+ server SDK returns the code identification result that is specified for the isAcCode parameter to the MPP client (step 5-6).

• If the value of the isAcCode parameter is true:

1. The MPP client sends the decoding request to Alipay+ client SDK (step 7-8).
2. Alipay+ calls the pay API with the code value (step 10).
3. The MPP server returns the payment URL to Alipay+ (step 11).
4. Alipay+ forwards the payment URL to Alipay+ client SDK, which then directs the user to the cashier page (step 12-14).
5. The user confirms to pay and the MPP server notifies Alipay+ of the payment result by using the notifyPayment API (step 14-17).
6. The MPP client redirects the user back to the merchant and the payment result page is displayed to the user (step 22-23).

• If the value of the isAcCode parameter is false, the MPP rejects the code and presents the message that the code value is invalid.

Notes:

• The figure illustrates the payment flow in the scenario where the merchant redirects the user to the wallet app for the payment. When the user uses the wallet app to scan the order code for the payment, step 2 should be replaced by the step in which the user scans the order code.
• The payment flow is based on the situation where the MPP uses the allowlist solution for code identification. For more information about code identification solutions, see Identify the code value.

About the redirection

To support the merchant in redirecting the user to the wallet app for the payment, the MPP needs to provide the payment URLs in the following three deep linking ways:

• Scheme
• App Link (for Android) / Universal Link (for iOS)
• WAP URL that can evoke a wallet app

Note:

When the wallet app is not installed, take the following things into consideration:

• If the wallet does not support the WAP URL, the scheme or the App Link/ Universal Link provided by the MPP is used to redirect users to the application download page.
• If the wallet supports the WAP URL, the wallet WAP page is evoked for users to continue the payment.

For more information about redirection, see Guide on redirections between the merchant and the Mobile Payment Partner.

Establish session between Alipay+ client SDK and Alipay+

Skip this step if the session is already created.

To ensure a secure communication between Alipay+ and Alipay+ client SDK, a session is created.

The following figure illustrates the workflow of establishing a session:

Figure 3. Workflow of establishing a session

Complete the following steps to establish a session:

1. Alipay+ client SDK calls the getAuthCode SPI to obtain the authorization code from MPP app (step 1).
2. MPP app returns the authorization code to Alipay+ client SDK (step 1.3).
3. Alipay+ client SDK sends the authorization code to Alipay+(step 2).
4. Alipay+ calls the applyToken API to obtain the access token from MPP server and MPP server returns the access token and customer ID to Alipay+ (step 2.1 and step 2.1.2).
5. Alipay+ creates the session ID (step 2.2).
6. Alipay+ returns the session ID to Alipay+ client SDK and the session is created (step 2.3).

Read the following sections for the main steps:

1. Call the getAuthCode interface to obtain the authorization code

Alipay+ client SDK calls the getAuthCode SPI to obtain the authorization code from MPP. The value of scopes is BASE_USER_INFO. MPP returns the authorization code by authCallback. For the samples for Android and iOS, see Alipay+ client SDK integration guide.

2. Obtain the customer ID and access token from wallet

Alipay+ client SDK sends the authCode to Alipay+. With the authCode received, Alipay+ calls the applyToken API to request access token. In this case, the value of acquirerId is fixed as 2052666000000000, which represents Alipay+. Alipay+ can request access token with the authCode received.

Process flow

The interface request contains the following fields:

The interface response contains the following fields:

Processing logic

If the access token is short-term valid, set the validity period to more than 10 minutes.

Mobile Payment Partner must be able to provide the refreshToken, and the validity period of the refreshToken must be greater than the validity period of the access token.

Refresh access token

When the original token expires, the AuthClient requests a new access token by using the refresh token. In this scenario, you can also use the applyToken interface. In addition, if the refresh request failed, Mobile Payment Partner must returna result.resultStatus of F and an error code that is corresponding to a specific reason.

• If the refresh token is invalid, returnINVALID_REFRESH_TOKEN
• If the refresh token expires, returnEXPIRED_REFRESH_TOKEN/INVALID_REFRESH_TOKEN

Sample

Request sample

{
  "acquirerId":"10221880000000****",
  "pspId":"10220880000000****",
  "authCode": "663A8FA9D83648EE8AA11FF68298****",
  "grantType": "AUTHORIZATION_CODE",
}

Response sample

{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5A****",
  "accessTokenExpiryTime": "2019-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C910****",
  "refreshTokenExpiryTime": "2019-06-08T12:12:12+08:00",
  "customerId":"278980891233213455671****"
}

More information

See applyToken for details.

3. Alipay+ creates the session and return session ID to Alipay+ client SDK

Alipay+ creates the session, and associates sessionId with the returned customerId and accessToken. Alipay+ returns the session ID to Alipay+ client SDK. The session is created between Alipay+ and Alipay+ client SDK.

By default, the validity period of the session is 30 minutes (set by Alipay+ for security reasons). Auth login is normally valid for 360 hours unless user logout.

Identify the code value

Wallet needs to design a solution, such as allowlist solution or blocklist solution, to identify the code and then process the code accordingly. It's recommended that MPP uses the allowlist solution. If the url is an http url, perform a urldecode first.

Allowlist solution

The following figure illustrates the allowlist solution flow:

Figure 4. MPP allowlist solution

The allowlist solution contains the following key points:

• If the code is a local code or in the allowlist of the wallet, the wallet processes the code according to its own business logic.
• If the code is neither a local code nor in the allowlist of the wallet,  wallet calls Alipay+ server SDK to identify the code. See Identify the code for details.

Blocklist solution

The following figure illustrates the blocklist solution flow:

Figure 5. MPP blocklist solution

The blocklist solution contains the following key points:

• If the code is in the blocklist, the MPP presents the message that the code is invalid and rejects the code.
• If the code is not in the blocklist and is a local code that is supported by the wallet, the wallet processes the code according to its own business logic.
• If the code is neither in the blocklist nor a local code supported by the wallet, wallet calls Alipay+ server SDK to identify the code value. See Identify the code for details.

Identify the code

Complete the following steps to identify the code by using Alipay+ server SDK. For more information about how to use Alipay+ server SDK, See Alipay+ server SDK integration guide.

1. Initialize the code identification service

Initialize Alipay+ server SDK by calling the ac.code.service.CodeIdentificationService#init interface.

CodeIdentificationInitResult result = codeIdentificationService.init();
if (result.getResult().getResultStatus().equals("S")){
    // Initialization success.
} else {
    // Block the application startup and troubleshoot
}

Result processing logic:

• If result.resultStatus is S, initialization is successful.
• If result.resultStatus is F or U, the application startup is blocked. Wallet can troubleshoot the problems based on result codes and logs.

2. Identify whether the code can be processed by Alipay+

Call the ac.code.service.CodeIdentificationService#identify interface to identify whether the code can be processed by Alipay+.

CodeIdentificationIdentifyRequest request = new CodeIdentificationIdentifyRequest();
request.setCodeValue("28100104df23423423423");
request.setOpenId("228770368287434384680");
CodeIdentificationIdentifyResult result = codeIdentificationService.identify(request);
if (result.getResult().getResultStatus().equals("S") && result.isAcCode()){
    // the code should be processed by AlipayConnect
}
if (result.getResult().getResultStatus().equals("F"){
    // Please pay attention to resultCode
}

Result processing logic:

• If result.resultStatus is S, the code identification is successful. See the following list for details:

• If isAcCode is true, the code can be processed by Alipay+ and wallet app must call Alipay+ client SDK's API to process this code with acDecodeConfig specified.
• If isAcCode is false, the code cannot be processed by Alipay+.

• If result.resultStatus is F, code identification is failed. MPP handles the result based on result codes.
• If result.resultStatus is U, unknown exceptions occur during the code identification and MPP can check logs to view details. MPP can also retry.

Decode the code value

If the code is identified as an Alipay+ code, wallet app can send a decoding request to Alipay+ client SDK to obtain the code value. For more information about how to use Alipay+ client SDK, see Alipay+ client SDK integration guide.  

Process flow

Complete the following steps to decode:

1. Initialize Alipay+ client SDK

Call the init interface that is for Android or the initWithContext interface that is for iOS to initialize Alipay+ client SDK at first.

2. Call the decode interface

Call the decode interface and send the decoding request to Alipay+.

Processing logic

The following rules apply:

• Invoke the cashier when the decoding succeeds.
• If the decoding failed, the wallet must be able to receive the error details from contained in the response, and presents certain message to user accordingly to indicate the error.
• Exceptional cases:

• If user has scaned the code, however, the code timeouts, wallet must present certain messages to user to indicate the timeout and encourage the user to retry.
• If user has scaned the code, however, the code is invalid, wallet must present certain messages to user to indicate that the code is invalid and encourage the user to retry.

Process the payment request from Alipay+

Mobile Payment Partner needs to process the payment requests sent from Alipay+by using the pay interface.

Process flow

The interface request contains the following fields:

The interface response contains the following field:

Processing logic

When processing payment requests, Mobile Payment Partner must pay attention to the following items:

• Use the timeout value assigned by Alipay+, if Alipay+ does not provide the timeout value, for Cashier Payment, set the timeout value as 10 minutes at most. When timeout occures, Mobile Payment Partner closes the payment order and returns an error code ORDER_IS_CLOSED.
• Mobile Payment Partner must be able to check the idempotency of payment requests by using paymentRequestId.
• Support all the currencies as defined in ISO 4217.
• Normal case: When the payment request is successfully submitted, return a result code PAYMENT_IN_PROCESS.
• Optional: Exceptional case: Verify the user status, if the status is abnormal, return a result.resultCode of USER_STATUS_ABNORMAL.

Sample

Cashier Payment request

{
  "order": {
    "referenceOrderId": "OrderID_010101****",
    "orderDescription": "SHOES",
    "orderAmount": {
      "value": "100",
      "currency": "JPY"
    },
    "merchant": {
      "referenceMerchantId": "M0000000****",
      "merchantMCC": "1405",
      "merchantName": "UGG",
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      }
    }
  },
  "acquirerId": "102218800000000****",
  "pspId": "102217200000000****",
  "paymentRequestId": "201811291907410100070000007****",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "281006050000000000125733DAHJ****"
  },
  "payToAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "paymentQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice": "10.0000"
  },
  "paymentFactor": {
    "isCashierPayment": "true",
    "isInStorePayment": "false"
  }
}

Cashier Payment response

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentId": "20181129190741010007000000****",
  "paymentTime": "2020-01-01T12:01:01+08:30"
}

More information

See pay for details.

Return the payment URL to SDK to present the cashier page

MPP returns the payment URL to SDK. Alipay+ client SDK opens the MPP payment URL by using the pay interface. User confirms to pay. For the samples for Android and iOS, see the Alipay+ client SDK integration guide.

Optional: Redirect the user back to the merchant page

MPP app redirects the user back to the merchant page when paymentRedirectUrl is specified in the payment request. The merchant presents the payment result to the user.

Wallet can use AC SDK to redirect user back to the merchant page, and the following rules apply:

• If the payment is successfully completed, the user must be redirected back to the merchant page.
• Optional: If the payment is not successfully completed, the user is redirected back to the merchant page. Wallet must present a result page to indicate that the payment failed.
• Optional: If the user cancels the payment in the wallet (payment cancel button exists), the user is redirected back to the merchant page.
• Wallet must trust Alipay+ merchant URL, so that the redirection can be successful without adding the Alipay+ merchant URL to whitelist.
• Wallet must support the redirection to merchant App by using scheme, Universal Link/App Link, or WAP-scheme.
• In the scan-to-pay scenario, do not redirect back to merchant App. Instead, it's suggested to redirect to wallet homepage.
• If the merchant page is a WAP page, redirect back to the merchant WAP page if the device is of Android system (due to system restrictions, do not redirect back to the merchant WAP page if the user is using an iOS device).
• If the merchant does not provide redirection address, do not redirect back to merchant page.