This chapter goes through the process of integrating the capability of accepting payments with the Alipay+ SDKs 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 Mobile Payment Provider (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.

• 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's allowlist, the MPP server calls the Alipay+ server SDK to identify the code (step 3).

4. If the value of the isSupported parameter (returned by the Alipay+ server SDK) is true, decode the code.

• If the code is identified as an entry code:

1. The MPP client calls the launch API of the Alipay+ client SDK to send the decoding request to Alipay+ client SDK (step 6)
2. Alipay+ client SDK redirects the user to the merchant's cashier page (step 7).
3. The user enters the payment amount on the merchant's cashier 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. The merchant/ACQP redirects the user to the Alipay+ URL (step 12).
7. Alipay+ client SDK intercepts the Alipay+ URL and parses the query parameter to obtain the code value (step 13).

Note: step 7 to step 13 is handled by Alipay+ and the MPP is not involved.

8. Alipay+ client SDK calls the decode API of the Alipay+ client SDK for decoding (step 14).

• If the code is identified as an order code, MPP Client sends the code value to Alipay+ to decode directly. For the following procedures, see step 15.

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

Notes:

1. 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.
2. To process payment requests from Acquiring Service Providers (ACQPs) that operate in mainland China, the MPP also needs to integrate the getAuthCode API of the Alipay+ client SDK and applyToken API.

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 Alipay+ MPP Server SDK.

1. Initialize the code identification service

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

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 API 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 by using the launch API of the Alipay+ client SDK. 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 at a fixed frequency, which needs to be at least once a day.

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. If the code is identified as an Alipay+ entry code, the wallet app can call the launch API of the Alipay+ client SDK to obtain the code value. For more information about how to use Alipay+ client SDK, see Alipay+ client SDK integration guide.
2. Alipay+ client SDK sends the code value to MPP Client for decoding.
3. The MPP client forwards the order code value to the MPP server.
4. For the next procedures, see Decode the code value.

Decode the code value

If the code is identified as an Alipay+ code 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":"5411",
          "merchantName":"UGG",
          "store":{
             "referenceStoreId":"S00xxxx0001",
             "storeName":"UGG-2",
             "storeMcc":"5411"
          }
       }
 }, 
  "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. The user confirms the information and completes the payment.

Optional: Redirect the user back to the merchant page

If the paymentRedirectURL parameter is specified in the pay API, the wallet app redirects the user back to the merchant side. The merchant then presents the payment result page to the user.

To obtain the capability of Alipay+ SDK to redirect the user back to the merchant side, the MPP needs to apply the following rules:

• If the payment is successfully completed, the MPP must redirect the user back to the merchant side, unless the user uses the wallet app to scan the order code for the payment. In the latter case, redirection back is not needed.
• The MPP must trust all URLs that are involved in Alipay+ transactions so that the user's redirection back to the merchant side won't be blocked.
• The MPP must support the redirection to the merchant side no matter whether the merchant provides a WAP page URL, URL scheme, App Link, or Universal Link.
• In the scenario where the user scans the QR code to place an order, it is recommended to redirect back to the wallet app's homepage, instead of the merchant side.
• If the user cancels the payment in the wallet app where a payment cancellation button exists, the MPP is recommended to redirect the user back to the merchant side for a better user experience.
• If the merchant does not provide a redirection address, it is not recommended to redirect the user back to the merchant side.