Alipay+ DocsAlipay+ Docs

Overview

For in-store payments in the Chinese mainland that are made by Alipay+ overseas Mobile Payment Partners (MPPs), the People's Bank of China proposes the following regulations:

  • For all in-store payments, the payment amount cannot exceed 35,000 CNY per transaction per individual and the accumulated payment amount cannot exceed 350,000 CNY per individual within a year.
  • For entry code payments, the payment amount cannot exceed 500 CNY per transaction per individual and the accumulated payment amount cannot exceed 50,000 CNY per individual within a year.

In response to these regulations, MPPs are required to upgrade their technical integrations with Alipay+ in the Merchant-presented Mode Payment (MPM) scenario. This topic introduces the upgrade solution and the user experience after the upgrade provided by MPPs in the MPM scenario.

Note: For the User-presented Mode Payment scenario, no upgrade is needed.

User experience

When the payment amount exceeds the limit as regulated by the People's Bank of China, MPPs need to display an error page to ensure that consumers are clearly reminded and notified. The error page is designed and provided by Alipay+.

The following figure shows the user experience that MPPs can provide to consumers after the upgrade:

image.png

A consumer processes the payment with the following steps:

  1. The consumer uses the MPP app to scan the QR code that is presented by the merchant.
  2. The consumer enters a payment amount in CNY and clicks Confirm.
  3. If the payment amount exceeds the limit, the consumer is redirected to an error page where a detailed message is displayed to explain the payment failure reason. Otherwise, the consumer completes the payment and is redirected to a payment result page.

Upgrade solution

Workflow

This section shows the workflows of making an in-store payment in the Chinese mainland, which are applicable to two different kinds of QR codes: entry code and order code.

Entry code

The following figure illustrates the workflow of making an in-store payment in the Chinese mainland with an entry code:

entry code.png

The workflow consists of the following steps:

  1. The merchant/ACQP displays the QR code to the user, and the user scans the QR code with the MPP app. (Step 1-2)
  2. The MPP client decodes the QR code and passes the code value to the MPP server. (Step 3)
  3. The MPP server identifies whether the code value can be decoded by Alipay+ and returns the identity result to the MPP client. (Step 4-5)
  4. The MPP client calls the launch API to require the Alipay+ client SDK to redirect the user to the merchant page. (Step 6)
  5. The merchant/ACQP displays an amount input page to the user, and the user inputs the payment amount. Then, the merchant/ACQP places an order to Alipay+, and Alipay+ constructs an order code URL and returns it to the merchant/ACQP. (Step 7-12)
  6. The merchant/ACQP passes the order code URL to the Alipay+ client SDK, and the Alipay+ client SDK intercepts and obtains the code value. (Step 13-14)
  7. The Alipay+ client SDK calls the decode API to request the MPP client for decoding. (Step 15)
  8. The MPP client SDK sends a decoding request to the MPP server. (Step 16)
  9. The MPP server calls the userInitiatedPay API to decode the code value and then Alipay+ handles its internal logic, for example, on payment limitations as follows: (Step 17-18)
    • If the payment amount exceeds the limit, Alipay+ assembles an error page and sets the value of the actionForm.actionType parameter in the userInitiatedPay API response as HANDLE_BY_SDK. (Step 19-20)
    • Otherwise, Alipay+ places an order to continue the payment process with the value of the actionForm.actionType parameter in the userInitiatedPay API response set as HANDLE_BY_PSP. (Step 21-22)
  1. Alipay+ returns values of the actionForm.actionType and actionForm.sdkActionPayload parameters, as well as the order information in response to the userInitiatedPay API. (Step 23)
  2. The MPP server takes different actions according to the value of the actionForm.actionType parameter that is returned by Alipay+ as follows:
    • 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, opening the error page. (Step 24-26)
    • If the value of actionForm.actionType is HANDLE_BY_PSP, the MPP server continues to process the payment or produces an error code if the payment fails, and returns the payment result to the MPP client. Correspondingly, the MPP client displays the payment result page to the user. (Step 27-29)

Order code

The following figure illustrates the workflow of making an in-store payment in the Chinese mainland with an order code:

order code.png

The workflow consists of the following steps:

  1. The merchant/ACQP sends the order information to Alipay+, and Alipay+ returns the QR code to the merchant/ACQP. (Step 1-2)
  2. The merchant/ACQP displays the QR code to the user, and the user scans the QR code with the MPP app. (Step 3-4)
  3. The MPP client decodes the QR code and passes the code value to the MPP server. (Step 5)
  4. The MPP server identifies whether the code value can be decoded by Alipay+ and returns the identity result to the MPP client. (Step 6)
  5. The MPP server calls the userInitiatedPay API to decode the code value and then Alipay+ handles its internal logic, for example, on payment limitations as follows: (Step 7-8)
    • If the payment amount exceeds the limit, Alipay+ assembles an error page and sets the value of the actionForm.actionType parameter in the userInitiatedPay API response as HANDLE_BY_SDK. (Step 9-10)
    • Otherwise, Alipay+ places an order to continue the payment process with the value of the actionForm.actionType parameter in the userInitiatedPay API response set as HANDLE_BY_PSP. (Step 11-12)
  1. Alipay+ returns values of the actionForm.actionType and actionForm.sdkActionPayload parameters, as well as the order information in response to the userInitiatedPay API. (Step 13)
  2. The MPP server takes different actions according to the value of the actionForm.actionType parameter that is returned by Alipay+ as follows: (Step 14)
    • 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 interface to pass actionForm.sdkActionPayload to the Alipay+ Client SDK. Correspondingly, Alipay+ Client SDK takes actions, for example, opening the error page. (Step 15-17)
    • If the value of actionForm.actionType is HANDLE_BY_PSP, the MPP server continues to process the payment or produces an error code if the payment fails, and returns the payment result to the MPP client. Correspondingly, the MPP client displays the payment result page to the user. (Step 18-20)

Highlights

To efficiently upgrade your integration with Alipay+, learn about the following highlights:

  • For the MPP server, the following actions need to be taken:
    • Add a new response object actionForm to the userInitiatedPay API, which consists of two child parameters called actionType and sdkActionPayload.
    • When Alipay+ returns the userInitiatedPay response, take different actions according to the value of actionForm.actionType.
      • If actionForm.actionType is HANDLE_BY_SDK, the MPP server passes actionForm.actionType and actionForm.sdkActionPayload to the MPP client, so that the MPP client can further call the Alipay+ client SDK.
      • If the value of actionForm.actionType is HANDLE_BY_PSP, the MPP server continues to process the payment or produces an error code if the payment fails, and returns the payment result to the MPP client.

It is noted that no matter whether the decoding succeeds or fails (the value of the result.resultStatus parameter returned by Alipay+ is S or F), the MPP server needs to take actions as above.

  • For the MPP client, the following actions need to be taken:
    • For an entry code payment:
      • If the MPP server passes the actionForm.actionType parameter with a value of HANDLE_BY_SDK, execute the callback function of the decode API to pass the value of actionForm.sdkActionPayload to the Alipay+ Client SDK.
      • If the MPP server passes the actionForm.actionType parameter with a value of HANDLE_BY_PSP, execute the callback function of the decode API after receiving the payment result from the MPP server.
    • For an order code payment:
      • Integrate a new Alipay+ Client SDK API called handleAction.
      • If the MPP server passes the actionForm.actionType parameter with a value of HANDLE_BY_SDK, call the handleAction API to pass the value of actionForm.sdkActionPayload to the Alipay+ Client SDK.

Related topics

To obtain more information to empower the upgrade, read the following topics:

  • handleAction

Learn more about

Home
Get Support
Need more help?