Alipay+ provides a set of APIs and SDKs for Mobile Payment Providers (MPPs) to implement the capability of making a payment in the scenario where a user uses an MPP app to scan the QR code that is presented by the merchant, which can be either an entry code or an order code.

To make a payment, the MPP needs to take the following steps:

• Step 1: Filter and identify the code
• Step 2: Decode the code
• Step 3: Render and present the cashier page
• Step 4: Redirect the user back to the merchant page

Workflow

The following figure illustrates the workflow of making a payment in the Merchant-presented Mode Payment scenario.

Notes:

• The following payment flow assumes that the merchant's code is an Alipay+ code and that the MPP uses the Alipay+ server SDK to identify the code. For more information, see Filter and identify the code.
• Step 7 to 12 and step 17 to 18 are handled by Alipay+ and the MPP is not involved.

Figure 1. Payment flow

The payment process consists of the following steps:

1. The user uses an MPP 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 code identification. (step 2)
3. The MPP server calls the Alipay+ server SDK to identify the the code type and whether the code is supported by Alipay+. (step 3)
4. The CodeIdentificationService#identifyCode API of the Alipay+ Server SDK returns the code identification result to the MPP server (step 4), which contains the following information:

• The isSupported parameter that indicates whether the code is supported by Alipay+.
• The postCodeMatchActionType parameter that indicates the code type.

5. The MPP decodes the code. Depending on the code type, the decoding process is different:

• If the code is identified as an entry code (postCodeMatchActionType=OPEN_URL):

1. The MPP server sends the code identification result to the MPP client. (step 5)
2. The MPP client calls the launch API of the Alipay+ client SDK to start the payment process. (step 6)
3. The Alipay+ client SDK redirects the user to the merchant. The merchant displays a cashier page to the user. (step 7-8)
4. The user enters the payment amount on the merchant cashier page. (step 9)
5. The merchant/ACQP places a payment order to Alipay+. (step 10)
6. Alipay+ constructs and sends a payment URL to the merchant/ACQP. The payment information is stored as a code value in the payment URL. (step 11-12)
7. (Optional) For the payment requests from ACQPs that operate in mainland China, the OAuth 2.0 process requires that the merchant obtains the MPP user ID. Therefore, the MPP needs to provide the access token and user ID to Alipay+ via the getAuthCode API of the Alipay+ client SDK and the server API applyToken.
8. The merchant/ACQP redirects the user to the MPP cashier page as specified by the payment URL. (step 17)
9. The Alipay+ client SDK intercepts the payment URL to obtain the code value. (step 18)
10. The Alipay+ client SDK calls the decode API to send the code value to the MPP client. (step 19)
11. The MPP client sends the decoding request with the code value to the MPP server. (step 20)

• If the code is identified as an order code (postCodeMatchActionType=DECODE): the MPP server can request that Alipay+ decode the code directly. See step 21 for the next steps.

6. The MPP server initiates a decoding request via the userInitiatedPay API. Alipay+ returns the payment information to the MPP server. (Step 21-22)
7. The MPP server forwards the payment information to the MPP client. (step 23)
8. The MPP client displays the cashier page, where the user confirms and completes the payment. (step 24-25)
9. The MPP processes the payment. The MPP server then notifies Alipay+ of the payment result via the notifyPayment API. (step 26-27)
10. Alipay+ notifies the merchant/ACQP of the payment result. (step 28)
11. The MPP server sends the payment result to the MPP client. The MPP client then displays the payment result page to the user. (step 29-30)
12. (Optional) If the paymentRedirectURL parameter is returned by Alipay+ in the userInitiatedPay API, the MPP redirects the user back to the payment result page of the merchant. (step 31-32)

Step 1: Filter and identify the code

After the user scans the QR code with the MPP app, the MPP must filter and identify the code before sending the code to Alipay+ for decoding.

Step 1.1 Filter the code

To decide whether the code is to be processed by the MPP or Alipay+, the MPP can filter the code with either of the following solutions:

• Allowlist solution: The MPP constructs a QR code allowlist to filter the codes.
• Blocklist solution: The MPP constructs a QR code blocklist to filter the codes.

See the following sections for details about each solution.

Allowlist solution

The following figure illustrates the process of filtering the code with an allowlist:

Figure 2. MPP allowlist solution

The MPP filters the code with the allowlist solution in the following steps:

1. The MPP constructs a QR code allowlist.
2. The MPP checks whether the code is an MPP local code or in the MPP allowlist.

• 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 then identify the code. For more information, see Step 1.2 Identify the code.

Blocklist solution

The following figure illustrates the process of filtering the code with a blocklist:

Figure 3. MPP blocklist solution

The MPP filters the code with the blocklist solution in the following steps:

1. The MPP constructs a QR code blocklist.
2. The MPP checks whether the code is in the MPP blocklist.

• If the code is in the MPP blocklist, the MPP rejects the code.
• If the code is not in the MPP blocklist, proceed.

3. The MPP checks whether the code is an MPP local code.

• If the code is an MPP local code, the MPP processes the code according to its own business logic.
• If the code is not an MPP local code, the MPP can then identify the code. For more information, see Step 1.2 Identify the code.

Step 1.2 Identify the code

The MPP identifies whether the code is supported by Alipay+ with either of the following methods:

• Call the Alipay+ server SDK APIs. For more information, see Use the Alipay+ server SDK.
• Obtain the Alipay+ code rules and use them locally. For more information, see Use the Alipay+ code rules locally.

For different code identification results, take actions as follows:

• If the code is supported by Alipay+, the MPP server requests Alipay+ to decode the code. For more information, see Step 2: Decode the code.
• Otherwise, the MPP processes the code according to its own logic.

Step 2: Decode the code

If the code is identified as an Alipay+ code, the MPP can proceed to decode the code to obtain the payment information. For Merchant-presented Mode Payment, the Alipay+ code can be either an order code or an entry code, the MPP can decode the codes accordingly:

• If the code is an Alipay+ order code, send a userInitiatedPay request to Alipay+ for decoding.
• If the code is an Alipay+ entry code, process the entry code first according to steps 5-20 as described in the Workflow, then send a userInitiatedPay request to Alipay+ for decoding.

Processing logic

When using the userInitiatedPay API, take the following things into consideration:

• Ensure the following parameters are configured properly in the request:

• codeValue: the code value that the user scans.
• customerId: the unique ID that is assigned by the MPP to identify a user.

• Handle the response properly, especially the following parameters:

• codeType: the type of code that the user scans. The following parameters are returned only when the value of the codeType parameter is ORDER_CODE and the decoding process is successful:

• order: the order information that is agreed upon by the user and the merchant. This information is used to render and display the cashier page in the MPP's terminal. For more information, see Step 3: Render and present the cashier page
• paymentAmount: the amount that Alipay+ requests to receive from the MPP.
• payToAmount: the amount that the MPP needs to settle to Alipay+.

• paymentRedirectURL: the URL where the user is redirected after the payment is completed. If this parameter is returned, the MPP needs to redirect the user back to the merchant side. For more information, see Step 4: Redirect the user back to the merchant.
• result: the decoding result. The MPP might receive different results from Alipay+. Follow the instructions below to handle the result.

For more information about how to use the API (such as the parameter description), see userInitiatedPay.

Sample

The following samples show the request and response when the MPP calls the Alipay+ userInitiatedPay API in the Merchant-presented Mode Payment scenario.

Request from the MPP to Alipay+

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

Response from Alipay+ to the MPP

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

Step 3: Render and present the cashier page

After receiving the payment information from the userInitiatedPay API response, the MPP renders and presents the cashier page to the user, where the payment details are displayed. The user then confirms the information and completes the payment.

(Optional) Step 4: Redirect the user back to the merchant

If the paymentRedirectURL parameter is returned by Alipay+ in the userInitiatedPay API response, the MPP needs to redirect the user back to the payment result page that is specified by the ACQP.

When implementing the capability of redirection back, apply the following rules:

• The MPP must use WebView to open the URL specified by the paymentRedirectURL.
• The MPP needs to trust all URLs that are involved in Alipay+ transactions so that the user redirection to the merchant side will not be blocked.
• If no paymentRedirectURL is passed, it is recommended to redirect the user back to the MPP app homepage, instead of the merchant side.