This chapter goes through the process of integrating the capability of accepting payments with the Alipay+ server SDK and APIs.

The process is used in the scenario where a user uses a wallet app to scan the QR code that is presented by the merchant, which can be either an entry code or an order code.

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 process consists of the following steps:

1. The user uses a wallet app to scan the QR code that is presented by the merchant (step 1).
2. The MPP client sends the code value to the MPP server for identification (step 2).
3. The MPP server identifies the code value.

• 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 returns the code identification result to the MPP client (step 3-4). 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 (step 5). For more information, see Use Alipay+ code rules locally.

4. According to the parameter values that are returned, take further actions.

• If the value of the isSupported parameter is true and the value of the postCodeMatchActionType parameter is OPEN_URL, follow these steps:

1. The MPP server returns the values of redirectUrl and userAgent to the MPP client (step 6).
2. The MPP client put the user agent in the redirect URL and open the constructed URL (step 7).
3. The merchant/ACQP displays the entry code URL page to the user and the user enters the payment amount on the page (step 8).
4. The merchant/ACQP places an order (step 9).
5. Alipay+ generates a new code value and constructs an URL for the order code (step 10-11).
6. Alipay+ returns the order code URL to the merchant/ACQP and the merchant/ACQP redirects back to the order code URL (step 12-13).
7. The MPP client forwards the new code value to the MPP server (step 14).
8. For the next procedures, see step 15.

• If the value of the isSupported parameter is true and the value of the postCodeMatchActionType parameter is DECODE, the MPP sends the code value to Alipay+ for decoding directly. See step 15.

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

5. The MPP server sends the decoding request to Alipay+ by calling the userInitiatedPay API (step 15).
6. Alipay+ decodes the code and returns the order information to the MPP server (step 16).
7. The MPP server generates the cashier page and returns the cashier page to the MPP client (step 17).
8. The MPP client displays the cashier page for the user to confirm the payment (step 18-19).
9. The MPP client completes the payment and notifies Alipay+ of the payment result (step 20-21).
10. The MPP client redirects back to the payment result page and the payment result is displayed to the user (step 25-26).

Note: The payment flow is based on the situation when the MPP uses the allowlist solution for the code identification. For more information about the code identification solution, see How to identify the code.

Identify the code

Allowlist solution

The following figure illustrates the allowlist solution flow:

Figure 2. 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 3. 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. The MPP can take further actions according to the following rules:

• If isSupported is true and postCodeMatchActionType is OPEN_URL, the MPP needs to open the entry code URL. For more information, see Open the entry code URL.
• If isSupported is true and postCodeMatchActionType is DECODE, 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.

Open the entry code URL

Note: Skip this step if the code is identified as an order code.

Follow these steps to process an entry code:

1. The MPP server receives the code identification result from Alipay+ server SDK or identifies the code based on Alipay+ code rules.
2. The MPP server returns the values of redirectURL and userAgent to the MPP client.
3. The MPP client puts the user agent in the redirect URL and opens the constructed URL.
4. The merchant/ACQP displays the entry code URL page to the user.
5. The user enters the payment amount and places an order.
6. Alipay+ generates an order code, identifies the user agent, and constructs the order code URL.
7. Alipay+ returns the order code URL to the merchant/ACQP and the merchant/ACQP redirects back to the order code URL.
8. The MPP client forwards the order code value to the MPP server.
9. For the next procedures, see Decode the code value.

Decode the code value

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

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 User Initiated Payment interface. 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 protocol.