Alipay+ DocsAlipay+ Docs

Private order code

In the Merchant-presented Mode Payment Private Order Code scenario, the Acquiring Partner (ACQP) issues a QR code to the merchant based on the order information that the merchant collects from the user. The merchant then displays the QR code to the user. After scanning the QR code, the user is redirected to the cashier page, where the user confirms the payment.

To integrate the Merchant-presented Mode Payment Private Order Code, the ACQP needs to complete the following steps:

Workflow

The following figure illustrates the workflow of accepting a payment in the Merchant-presented Mode Payment Private Order Code scenario.

image

Figure 1. Workflow of accepting a payment

The payment process consists of the following steps:

  1. When a user purchases goods, the merchant confirms the payment amount with the user. (Step 1-2)
  2. The merchant sends the order information to the ACQP, which generates and returns a QR code to the merchant. The merchant then displays the QR code to the user. (Step 3-7)
  3. After the user scans the QR code, the (Mobile Payment Provider) MPP app sends a request to Alipay+ to decode the QR code. Alipay+ calls the userInitiatedPay API to send a decoding request to the ACQP.(Step 8-10)
  4. The ACQP processes the decoding request and returns order information to Alipay+. Alipay+ syncs the order information to the MPP app, which then renders the cashier page for the user to confirm the payment. (Step 11-14)
  5. After the user confirms the payment at the MPP side, Alipay+ processes the payment and calls the notifyPayment API to notify the ACQP of the payment result, which is then synced to the merchant. At the same time, the ACQP can initiate an inquiryPayment request to obtain the payment result asynchronously. (Step 15-21)

Step 1. Create a private order code

A private order code is a QR code representing an HTTPS URL. The ACQP needs to create a unique QR code for each order submitted by the merchant.

To ensure the QR code can be identified by Alipay+-supported wallets, the ACQP needs to provide rules on how to identify the QR code to the Alipay+ Solution Architect.

Step 2. Handle the userInitiatedPay request

After a user uses an Alipay+-supported digital wallet to scan the private order code, the wallet sends a request to Alipay+ to decode the QR code. Since the QR code is generated by the ACQP, Alipay+ sends a decoding request to the ACQP by calling the userInitiatedPay API. For each QR code, the ACQP needs to keep the order details in the ACQP system and return the order details to Alipay+ as per request.

Processing logic

When handling the userInitiatedPay request, pay attention to the following things:

  • If multiple requests with the same codeValue are received, return the same response parameters, including paymentRequestId.
  • After returning the order information, monitor the payment result notifications sent from Alipay+and use the inquiryPayment API to proactively query payment results.

Sample

Alipay+ sends the request to the ACQP.

copy
{
  "acquirerId": "2021228100000000",
  "pspId": "1022172000000000000",
  "codeValue": "http://a.com/2810060438884961634",
  "customerId": "208812211210000"
}

The ACQP returns the response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "codeType": "ORDER_CODE",
  "order": {
    "referenceOrderId": "OrderID_010101001",
    "orderDescription": "SHOES",
    "orderAmount": {
      "value": "100",
      "currency": "JPY"
    },
    "merchant": {
      "referenceMerchantId": "M0000000001",
      "merchantMCC": "5411",
      "merchantName": "UGG",
      "store": {
        "referenceStoreId": "S000000001",
        "storeName": "UGG-2",
        "storeMCC": "5411"
      },
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      }
    },
    "env": {
      "storeTerminalId": "122222",
      "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
    }
  },
  "paymentRequestId": "20200101234567890000",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "paymentFactor": {
    "isInStorePayment": "true",
    "isCashierPayment": "true",
    "inStorePaymentScenario": "OrderCode"
  },
  "settlementStrategy": {
    "settlementCurrency": "USD"
  },
  "paymentNotifyUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
  "paymentRedirectUrl": "https://alipay.com"
}

More information

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

Step 3. Handle the payment result

To ensure that the ACQP gets the payment result after the payment is processed, Alipay+ provides the following two APIs for the ACQP:

  • notifyPayment: This API is used by Alipay+ to notify the ACQP of payment results. Once the payment is processed, Alipay+ will send the payment result in a short, certain time period, for example, 10 seconds. For more information about how to receive notifications from Alipay+, see Receive payment notification.
  • inquiryPayment: This API is used by ACQPs to inquire about payment results. When the notifyPayment API fails to access ACQPs due to any network issues, this API can help ensure that ACQPs can get the final payment result. For more information about how to receive notifications from Alipay+, see Inquire about payment result.

In the Merchant-presented Mode Payment scenario, the notifyPayment and inquiryPayment APIs are both required to be integrated, thus working together to ensure ACQPs obtain the final payment result. Refer to the Collaboration between inquiryPayment and notifyPayment section to learn about how to handle the payment statuses that are obtained via these two APIs, as well as ensure the accuracy of the final payment result.