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: Render the Scan page
• Step 2: Filter and identify the code
• Step 3: Decode the code
• Step 4: Process the payment
• Step 5: Return the payment result
• Step 6: Redirect the user back to the merchant page

Workflow of making a payment

The following figures illustrate the workflows of making a payment in the Merchant-presented Mode Payment scenario with the following two types of QR codes:

• Order code: indicates a dynamic QR code that is generated for each order, whose value contains the order information such as merchant name, payment method, and order amount. An order code can be decoded directly by Alipay+.
• Entry code: indicates a static QR code that redirects the user to an amount input page. An entry code needs to be constructed to an order code before it can be decoded by Alipay+.

Notes:

• The following workflows assume that the merchant's QR 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.
• To process payment requests from merchants and ACQPs that operate in the Chinese mainland, the MPP client needs to obtain the MPP user ID through the OAuth 2.0 process. For more information, see Workflow of making a payment in the Chinese mainland.

Order code

Figure 1. Workflow of making a payment with an order code

The payment flow consists of the following steps:

1. The user opens the Scan page in the MPP app. (Step 1)
2. The MPP app calls the getAcceptanceMarkLogos API from Alipay+ Client SDK to obtain the logos of acceptance marks. (Step 2)
3. The MPP app obtains the logos of acceptance marks and displays them on the Scan page. (Steps 3-4)
4. The user uses the MPP app to scan the QR code that is presented by the merchant. (Step 5)
5. The MPP client sends the code value to the MPP server for code identification. (Step 6)
6. The MPP server calls the Alipay+ server SDK to identify the code type and whether the code is supported by Alipay+. (Step 7)
7. The CodeIdentificationService#identifyCode API of the Alipay+ server SDK returns the code identification result to the MPP server, which contains the following information: (Step 8)

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

8. When the code is identified as an order code (postCodeMatchActionType=DECODE), the MPP server calls the userInitiatedPay API to request Alipay+ to decode the code value. (Step 9)
9. Alipay+ handles its internal logic by setting different values for the actionForm.actionType parameter in the userInitiatedPay API response as follows: (Step 10)

• If there is no special business need, Alipay+ sets the value of the actionForm.actionType as HANDLE_BY_PSP.
• If there is any special business need, for example, the user needs to be redirected to an error page where a message is displayed to explain the payment failure reason, Alipay+ sets the value of actionForm.actionType as HANDLE_BY_SDK.

10. Alipay+ returns the payment information, as well as values of the actionForm.actionType and actionForm.sdkActionPayload parameters to the MPP server. (Step 11)
11. The MPP processes the payment depending on the value of actionForm.actionType:

• If the value of actionForm.actionType is HANDLE_BY_PSP, the MPP server forwards the payment information to the MPP client, and the MPP client displays the cashier page, where the user confirms and completes the payment. (Step 12-13)
• If the value of actionForm.actionType is HANDLE_BY_SDK, the MPP server passes actionForm.actionType and actionForm.sdkActionPayload to the MPP client, and the MPP client calls the handleAction API to pass actionForm.sdkActionPayload to the Alipay+ Client SDK. Correspondingly, Alipay+ Client SDK takes actions, for example, assembling and opening the error page. (Step 14-16)

12. The user confirms the payment and the MPP server notifies Alipay+ of the payment result via the notifyPayment API. (Step 17-19)
13. Alipay+ notifies the merchant/ACQP of the payment result. (Step 20)
14. The MPP server sends the payment result to the MPP client. The MPP client then displays the payment result page to the user. (Step 21-22)
15. 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 23-24)

Entry code

Figure 2. Workflow of making a payment with an entry code

The payment flow consists of the following steps:

1. The user opens the Scan page in the MPP app. (Step 1)
2. The MPP app calls the getAcceptanceMarkLogos API from Alipay+ Client SDK to obtain the logos of acceptance marks. (Step 2)
3. The MPP app obtains the logos of acceptance marks and displays them on the Scan page. (Steps 3-4)
4. The user uses the MPP app to scan the QR code that is presented by the merchant. The MPP should enable access to both HTTP and HTTPS URLs when the user scans an entry code. (Step 5)
5. The MPP client sends the code value to the MPP server for code identification. (Step 6)
6. The MPP server calls the Alipay+ server SDK to identify the code type and whether the code is supported by Alipay+. (Step 7)
7. The CodeIdentificationService#identifyCode API of the Alipay+ server SDK returns the code identification result to the MPP server, which contains the following information: (Step 8)

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

8. When the code is identified as an entry code (postCodeMatchActionType=OPEN_URL), the MPP decodes the code by following the steps below:

1. The MPP server sends the code identification result to the MPP client. (Step 9)
2. The MPP client calls the launch API of the Alipay+ Client SDK to start the payment process. (Step 10)
3. The Alipay+ Client SDK redirects the user to the merchant. The merchant displays an amount input page to the user. (Step 11-12)
4. The user enters the payment amount on the amount input page and the merchant/ACQP places a payment order to Alipay+. (Step 13-14)
5. Alipay+ constructs and sends an order code URL to the merchant/ACQP. The payment information is stored as a code value in the order code URL. (Steps 15-16)
6. The merchant/ACQP passes the order code URL to the Alipay+ Client SDK. Then, the Alipay+ Client SDK intercepts the order code URL to obtain the code value. (Step 17-18)
7. The Alipay+ Client SDK calls the decode API to send the code value to the MPP client. (Step 19)
8. The MPP client sends the decoding request with the code value to the MPP server. (Step 20)
9. The MPP server calls the userInitiatedPay API to request Alipay+ to decode the code value. (Step 21)

9. Alipay+ handles its internal logic by setting different values for the actionForm.actionType parameter in the userInitiatedPay API response as follows: (Step 22)

• If there is no special business need, Alipay+ sets the value of the actionForm.actionType as HANDLE_BY_PSP.
• If there is any special business need, for example, the user needs to be redirected to an error page where a message is displayed to explain the payment failure reason, Alipay+ sets the value of actionForm.actionType as HANDLE_BY_SDK.

10. Alipay+ returns the payment information, as well as values of the actionForm.actionType and actionForm.sdkActionPayload parameters to the MPP server. (Step 23)
11. The MPP processes the payment depending on the value of actionForm.actionType:

• If the value of actionForm.actionType is HANDLE_BY_PSP, the MPP server forwards the payment information to the MPP client, and the MPP client displays the cashier page, where the user confirms and completes the payment. (Step 24-25)
• If the value of actionForm.actionType is HANDLE_BY_SDK, the MPP server passes actionForm.actionType and actionForm.sdkActionPayload to the MPP client, and the MPP client executes the callback function of the decode API to pass actionForm.sdkActionPayload to the Alipay+ Client SDK. Correspondingly, Alipay+ Client SDK takes actions, for example, assembling and opening the error page. (Step 26-30)

12. The user confirms the payment and the MPP server notifies Alipay+ of the payment result via the notifyPayment API. (Step 29-31)
13. Alipay+ notifies the merchant/ACQP of the payment result. (Step 32)
14. The MPP server sends the payment result to the MPP client. The MPP client then displays the payment result page to the user. If the value of actionForm.actionType is HANDLE_BY_PSP, it is recommended that the MPP client executes the callback function of the decode API. (Step 33-35)
15. 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 36-37)

Step 1: Render the Scan page

When the MPP identifies that a user is in a region where the Alipay+ payment method is available, the Scan page needs to be rendered with varied acceptance marks. To prepare the Scan page, the MPP needs to call the getAcceptanceMarkLogos API from Alipay+ Client SDK. The following figure illustrates the workflow of obtaining logos of acceptance marks.

Figure 3. Workflow of obtaining logos of acceptance marks

The process of obtaining the logos of acceptance marks consists of the following steps:

1. The user opens the Scan page in the MPP app (Step 1).
2. The MPP app calls the getAcceptanceMarkLogos API from Alipay+ Client SDK to obtain the logos of acceptance marks. The MPP can determine whether to pass in the region parameter in the API request (Step 2).
3. (Optional) If the configuration information is not cached locally or if more than 24 hours have elapsed since Alipay+ Client SDK last pulls the configuration information, Alipay+ Client SDK calls the fetchConfig API to obtain the configuration information from the Alipay+ server (Steps 3-4).
4. The MPP app obtains the logos of acceptance marks in either of the following ways (Steps 5-9):

• If the region parameter is not passed in by the MPP, Alipay+ Client SDK determines the user's current location based on the cellular service provider information and/or the time zone obtained from the MPP app. Alipay+ Client SDK then retrieves the logos of acceptance marks from the configuration information and returns them to the MPP app.
• If the region parameter is passed in by the MPP, Alipay+ Client SDK directly obtains the logos of acceptance marks from the configuration information and returns them to the MPP app.

Note: If Alipay+ is not supported in the user's current location, Alipay+ Client SDK returns an empty array.

5. The MPP app displays the logos of acceptance marks accordingly on the Scan page (Step 10).

For more information about the requirements on the Scan page, see Scan page. Then, the user scans the QR code presented by the merchant.

Step 2: 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.

Note:

To ensure that the MPP can obtain the code value, the MPP app needs to be able to recognize different types of QR codes, including inverted QR codes. For more information, see Code format specification.

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 4. 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 2.2 Identify the code.

Blocklist solution

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

Figure 5. 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 2.2 Identify the code.

2. Identify the code

The MPP identifies whether the code is supported by Alipay+ by calling the Alipay+ server SDK APIs. For more information, see How to identify Alipay+ codes.

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 3: Decode the code.
• Otherwise, the MPP processes the code according to its own logic.

Step 3: 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 9-20 as described in the workflow of making a payment with an entry code, 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.
• paymentAmount: the amount that Alipay+ requests to receive from the MPP.
• payToAmount: the amount that the MPP needs to settle to Alipay+.

• actionForm.actionType: the type of further action that the MPP needs to take in different business scenarios. When Alipay+ determines that the MPP needs to request the Alipay+ Client SDK to meet its special business need, Alipay+ sets the value of this parameter as HANDLE_BY_SDK; otherwise, Alipay+ sets it as null orHANDLE_BY_PSP. For example, if the MPP needs to meet the regulations on the payment amount limitations for in-store payments in the Chinese mainland, Alipay+ sets the value of this parameter as HANDLE_BY_SDK.
• 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 6: 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 4: Process the payment

After receiving the userInitiatedPay response, the MPP processes the payment. Depending on the code type and the value of the actionForm.actionType parameter, the payment process is different:

• If the code is an Alipay+ order code, follow steps 12-16 as described in the workflow of making a payment with an order code.
• If the code is an Alipay+ entry code, follow steps 24-30 as described in the workflow of making a payment with an entry code.

Step 5: Return the payment result

After the payment is processed, the MPP needs to inform both the user and Alipay+ of the payment result by taking the following actions:

• Display the Payment Result Page to the user in the MPP app. For how to design the payment result page, see Payment Result Page.
• Return the payment result to Alipay+ in the request of notifyPayment API or the response of the inquiryPayment API. For more information, see Return payment results.

Step 6: 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.

Appendix

Workflow of making a payment in the Chinese mainland

To process payment requests from merchants and ACQPs that operate in the Chinese mainland, the merchant needs to obtain the MPP user ID through the OAuth 2.0 process. Therefore, the MPP client needs to integrate the getAuthCode API of the Alipay+ Client SDK (version 2.43.0 or higher) and the MPP server needs to integrate the applyToken API.

The following figure illustrates the workflow of making a payment in the Chinese mainland.

Figure 6. Workflow of making a payment in the Chinese mainland

The additional authorization process of obtaining the MPP user ID consists of the following steps (Steps 10-28):

1. The MPP calls the launch API of the Alipay+ Client SDK to start the payment process (Step 10).
2. The Alipay+ Client SDK redirects the user to the merchant page along with a user agent string that represents the Alipay wallet (Step 11).
3. The merchant/ACQP identifies the user agent string and composes the Alipay authorization URL (Step 12).
4. Before the merchant/ACQP redirects the user to the Alipay authorization URL, the URL is intercepted by the Alipay+ Client SDK (Steps 13-14).
5. The Alipay+ Client SDK sends the Alipay authorization URL to Alipay+ and then obtains the MPP authorization information from Alipay+. The authorization information consists of the merchant redirection URL, authorization scope, and the authClientId parameter (Steps 15-17).
6. With the MPP authorization information, the Alipay+ Client SDK calls the getAuthCode API to obtain the authorization code from the MPP client (Step 18).
7. The MPP server generates and returns the authorization code to the MPP client, which syncs the authorization code to the Alipay+ Client SDK (Steps 19-21). The authorization code that the MPP returns needs to meet the following conditions:

• The authorization code is within 32 bits in length.
• The prefix of the authorization code is in the format of 281***13, where the *** part is the routing number assigned by Alipay+.
• The authorization code is valid for at least 5 minutes and can be used only once.

8. The Alipay+ Client SDK redirects the user to the merchant page whose redirection URL contains the authorization code (Step 22).
9. The merchant/ACQP identifies the authorization code and calls Alipay+ to request an access token (Steps 23-24).
10. Alipay+ calls the applyToken API to request an access token from the MPP server (Step 25).
11. The MPP server returns the access token and customer ID to Alipay+ (Step 26).
12. With the customer ID, Alipay+ creates an Alipay user ID and syncs it to the merchant/ACQP (Steps 27-28).

Notes:

• It is recommended that the MPP use an accelerated domain name to enable faster access to Alipay+. For more information, see Overview.
• Check if the MPP server has IP access restrictions. If so, the MPP server needs to add the domain names of merchants and ACQPs to its whitelist or the user needs to use VPN in the Chinese mainland.
• The MPP needs to obtain the ICP (Internet Content Provider) license for the domain name used in the Chinese mainland.