Private order code
In the Merchant-presented Mode Payment Private Order Code scenario, the Acquiring Service Provider (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:
- Step 1. Create a private order code
- Step 2. Handle the userInitiatedPay request
- Step 3. Handle the payment result
Workflow
The following figure illustrates the workflow of accepting a payment in the Merchant-presented Mode Payment Private Order Code scenario.
Figure 1. Workflow of accepting a payment
The payment process consists of the following steps:
- When a user purchases goods, the merchant confirms the payment amount with the user. (Steps 1-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. (Steps 3-7)
- 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. (Steps 8-10)
- The ACQP processes the decoding request and returns order information to Alipay+. Alipay+ syncs the order information to the MPP app. (Steps 11-12)
- The merchant can initiate polling with the ACQP to inquire about the payment result. The ACQP then calls the inquiryPayment API to request the payment result from Alipay+. (Steps 13-16)
- With the order information, the MPP app renders the cashier page for users to confirm the payment. (Steps 17-18)
- The MPP app processes the payment and notifies Alipay+ of the payment result. Alipay+ then calls the notifyPayment API to notify the ACQP of the payment result, which is then synced to the merchant. (Steps 19-22)
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.
{
"acquirerId": "2021228100000000",
"pspId": "1022172000000000000",
"codeValue": "http://a.com/2810060438884961634",
"customerId": "208812211210000"
}
The ACQP returns the response to Alipay+.
{
"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/automation/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.