This chapter goes through the process of integrating the capability of accepting payments with Alipay+ server SDK and APIs. This process is applicable when the terminal type of the MPP client is App, Web, or WAP.

The following two scenarios are supported:

• After the user places an order, the merchant redirects the user to the cashier page inside the MPP's wallet app or on the MPP's Web/WAP page to complete the payment.
• After placing an order, the user uses the MPP's wallet app to scan the order code for the payment.

Overview

The following figure illustrates the payment flow:

Figure 1. Payment flow

The payment process consists of the following steps:

1. The user places an order, chooses a payment method and the merchant 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 code 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 value 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 can identify the code in one of the following two ways:

• The MPP server calls Alipay+ server SDK to identify the code and Alipay+ Server SDK returns the code identification result that is specified for the isSupported parameter to the MPP server (step 4-5).
• The MPP server obtains and saves Alipay+ code rules in advance by calling the inquiryCodeRules API, and uses the local code rules that are synchronized from Alipay+ to identify the code (step 6).

• If the value of the isSupported parameter is true:

1. The MPP server calls the userInitiatedPay API to send the decoding request (step 7).
2. Alipay+ returns the userInitiatedPay response with the order information (step 8-9).
3. The user is redirected to the payment page to confirm and complete the payment (step 10-12).
4. The MPP server notifies Alipay+ of the payment result by using the notifyPayment API (step 13).
5. Alipay+ notifies the merchant/ACQP of the payment result and the user is redirected back to the merchant payment result page (step 14-18).

• If the value of the isSupported parameter is false, the MPP server rejects the code and presents the message to the user that the code value is invalid.

Notes:

• The figure illustrates the payment flow in the scenario where the merchant redirects the user to the cashier page to complete the payment. When the user uses the MPP's 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 when the MPP uses the allowlist solution for code identification. For more information about the code identification solution, see Identify the code value.

About the redirection

If the MPP does not provide a wallet app, the MPP must provide the capability of redirecting users to a Web/WAP wallet page; otherwise, this capability can be used as a relegation option. The MPP needs to provide the Web/WAP implementation of the wallet for the merchant to redirect users to (refer to step 2: Redirect the user to the cashier page with the code value, Figure 1). For more information about redirection, see Guide on redirections between the merchant and the Mobile Payment Partner.

Identify the code

Allowlist solution

The following figure illustrates the allowlist solution flow:

Figure 3. MPP allowlist solution

The allowlist solution contains the following key points:

• If the code is an MPP local code or in the MPP allowlist, the MPP processes the code according to its own business logic.
• If the code is neither an MPP local code nor in the MPP allowlist, the MPP can identify the code in one of the following two ways:

• The MPP server calls Alipay+ server SDK to identify the code. For more information, see Use Alipay+ server SDK.
• The MPP server uses the local code rules that are synchronized from Alipay+ to identify the code. For more information, see Use Alipay+ code rules locally.

Blocklist solution

The following figure illustrates the blocklist solution flow:

Figure 4. 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 MPP processes the code according to its own business logic.
• If the code is neither an MPP local code nor in the blocklist, the MPP can identify the code in one of the following two ways:

• The MPP server calls Alipay+ server SDK to identify the code. For more information, see Use Alipay+ server SDK.
• The MPP server uses the local code rules that are synchronized from Alipay+ to identify the code. For more information, see Use Alipay+ code rules locally.

How to identify the code

Use Alipay+ server SDK

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

1. Initialize the code identification service

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

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, the initialization is successful.
• If result.resultStatus is F or U, the application startup is blocked. The MPP 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#identifyCode SPI to identify whether the code can be processed by Alipay+.

CodeIdentificationIdentifyRequest request = new CodeIdentificationIdentifyRequest();
request.setCodeValue("28100104df2342342****");
CodeIdentificationIdentifyResult result = codeIdentificationService.identifyCode(request);
if (result.getResult().getResultStatus().equals("S") && result.isSupported()){
  // the code should be processed by Alipay+
}
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 isSupported is true, the code can be processed by Alipay+ and the MPP needs to call the userInitiatedPay API to decode.
• If isSupported is false, the code cannot be processed by Alipay+.

• If result.resultStatus is F, the code identification is failed. The MPP can troubleshoot the result based on result codes.
• If result.resultStatus is U, unknown exceptions occur during the code identification and the MPP can check logs to view details, or try to call the interface again later.

Use Alipay+ code rules locally

For the MPP who doesn't want to use Alipay+ server SDK, the MPP can use Alipay+ code rules to identify the code locally. Follow these steps:

1. Inquire about Alipay+ code rules

Before the code identification, the MPP server requests to obtain Alipay+ code rules by calling the inquiryCodeRules API. If the request succeeds, the MPP obtains and saves Alipay+ code rules on its server.

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

When receiving a code, the MPP uses the code rules that are synchronized from Alipay+ to identify the code locally. For more information about the use of Alipay+ code rules, see Alipay+ code rules.

Note: To ensure the local code rules are synchronized with Alipay+, the MPP server needs to update the code rules in a fixed frequency, for example, daily in the morning.

Decode the code value

If the code is identified as an Alipay+ code, the MPP can send a userInitiatedPay request (with codeValue contained) to Alipay+ to decode.

Process flow

The API request contains the following parameters:

The API response contains the following parameters:

Processing logic

When using the API, the MPP needs to handle the result according to the following rules:

• If the decoding succeeds (result.resultStatus is S), the MPP invokes the cashier.
• If the decoding failed (result.resultStatus is F), the MPP must be able to receive the error details contained in the response, and presents certain messages to the users accordingly to indicate the error.
• If the decoding result is unknown (result.resultStatus is U), the MPP needs to try again until the value of result.resultStatus becomes S or F.

Sample

Request

{
  "codeValue":"http://xxxxx/281xxxxxxxxxxxxxxxx4441",
  "customerId":"2088xxxxxxxxxxx001"
}

Response

{
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
  "acquirerId": "102xxxxxxxxxxxx0001",
  "pspId":"102xxxxxxxxxxxx0001",
  "order":{
    "referenceOrderId":"OrderID_0101010101",
    "orderDescription":"SHOES",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    },
       "merchant":{
          "referenceMerchantId":"M00xxxxx0001",
          "merchantMcc":"1405",
          "merchantName":"UGG",
          "store":{
             "referenceStoreId":"S00xxxx0001",
             "storeName":"UGG-2",
             "storeMcc":"1405"
          }
       }
 }, 
  "codeType":"ORDER_CODE",
  "paymentRequestId":"202xxxxxxxxxxxxx0133",
  "paymentAmount":{
    "value":"100",
    "currency":"JPY"
  },
  "payToAmount":{
    "value":"1000",
    "currency":"KRW"
 },
  "paymentQuote":{
    "quoteId":"1234567",
    "quoteCurrencyPair":"JPY/KRW",
    "quotePrice":"10.0000"
  },
  "paymentFactor":{
     "isInStorePayment":"true" 
  }
}

More information

See userInitiatedPay for details.

Render and present the cashier page

MPP presents the cashier page and displays the order information. User confirms the information and completes the payment.

Optional: Redirect the user back to the merchant page

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

In addition, 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.
• In merchant App to Wap cashier scenario, wallet must support the redirection to merchant App by using scheme, or Universal Link/App Link.
• In merchant Wap to Wap cashier scenario, wallet must support the redirection to merchant Wap page.
• Wallet must support the redirection to merchant App by using the https protocal.