# Entry code In the Merchant-presented Mode Payment Entry Code scenario, the Acquiring Service Provider (ACQP) issues a QR code to the merchant, who displays the QR code at the merchant store. After scanning the QR code, the user is prompted to enter the payment amount and then redirected to the cashier page, where the user confirms the payment. To integrate Merchant-presented Mode Payment Entry Code, the ACQP needs to complete the following steps: - [Step 1. Create an entry code](#eQqdq) - [Step 2. Identify the wallet and route the payment](#ZBmuL) - [Step 3. Initiate a payment](#6HzDr) - [Step 4. Handle the payment result](#u96ck) ## Before you begin Before you begin, learn about the following concepts: - **Alipay+ wallet**: Refers to Alipay+'s Mobile Payment Provider such as AlipayCN, KaKaoPay, and GCash. Orders from Alipay+ wallets are processed according to Alipay+'s logic. - **Direct integration**: Refers to the situation where the ACQP integrates with a wallet independently, without Alipay+. Orders from a directly integrated wallet are processed according to the ACQP's logic, even if the directly integrated wallet is an Alipay+ wallet. ## Workflow The following figure illustrates the workflow of accepting a payment in the Merchant-presented Mode Payment Entry Code scenario. ![MPM Entry Code (ACQP).png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1729668809667-0a3329ff-5a70-4107-9c74-540e9d0fc89b.png) Figure 1. Workflow of accepting a payment The payment process consists of the following steps: 1. After a user scans the entry code, the Mobile Payment Provider (MPP) app opens an amount input page. (Steps 1-2) 2. The ACQP identifies the Alipay+ wallet and then renders the amount input page for users to enter the payment amount. (Steps 3-5) 3. The ACQP calls the **pay** API to place an order with Alipay+, which then returns _paymentUrl_ to the ACQP. (Steps 6-8) 4. Upon redirecting the user to the cashier page using _paymentUrl_, the ACQP can initiate polling with Alipay+ to inquire about the payment result by calling the **inquiryPayment** API. (Steps 9-11) 5. The MPP app renders the cashier page for users to confirm the payment. (Steps 12-13） 6. 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 14-17) ## Step 1. Create an entry code An Entry Code is a QR code representing an encoded URL that points to a WAP page. The ACQP needs to create an Entry Code and generate an Entry Code WAP page where users can enter a payment amount. Ensure that the WAP page meets the following requirements: - The WAP page can only be accessed by using the HTTPS protocol. - The WAP page needs to display input fields to users to collect payment information such as payment amount. - The WAP page needs to be transformed into a QR code, which is to be printed and presented at the merchant's store. In addition, to ensure the Entry Code WAP page can be opened in MPP apps that support Alipay+ as a payment method, the ACQP needs to provide the domain name of the WAP page URL to the Alipay+ Solution Architect. ## Step 2. Identify the MPP and route the payment When a user scans the entry code, the user enters the payment amount on the Entry Code WAP page to place an order. After receiving the order information from the merchant, the ACQP needs to identify the MPP by checking the user agent string in requests to access the Entry Code WAP page and then route the payment accordingly. The following figure illustrates the routing logic: ![4.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1682401896658-de399515-471e-4936-868a-82857f2091e2.png) Figure 2. Routing logic The routing logic is explained as follows: 1. If the user agent matches a wallet that is directly integrated with the ACQP, route the payment to the specific MPP and skip the following steps. 2. If the user agent matches **AlipayCN** as shown in the [mapping table](#DY6ru), 1. If **AlipayCN** is directly integrated with the ACQP**,** route the payment to **AlipayCN** and skip the following steps. 2. If **AlipayCN** is not directly integrated with the ACQP**,** route the payment to Alipay+ by calling the **pay** API. For more information, see [Step 3: Initiate a payment](#6HzDr). 3. If the user agent matches other Alipay+ MPPs as shown in the [mapping table](#DY6ru), route the payment to Alipay+ by calling the **pay** API. For more information, see [Step 3: Initiate a payment](#6HzDr). 4. If the user agent does not match any MPPs as shown in the [mapping table](#DY6ru), the ACQP can handle the order with its logic and skip the following steps. ### Mapping between MPP and user agent string The following table describes the mapping relationship between an MPP and its user agent (UA) string, where - The **MPP** column indicates which MPP the user agent represents. - The **Full User Agent String** column contains examples of the UA strings. - The **UA Identifier** column indicates which part of the Full User Agent String can be used to identify the UA. The user agent string can be used to identify an MPP if the string contains the corresponding **UA Identifier**. | **MPP** | **Full User Agent String** | **UA Identifier** | | --- | --- | --- | | Alipay CN | Mozilla/5.0 (iPhone; CPU iPhone OS 14\_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/18D52 Ariver/1.1.0 AliApp(AP/10.2.15.6000) Nebula WK RVKType(1) AlipayDefined(nt:4G,ws:414\|672\|3.0) **AlipayClient**/10.2.15.6000 Alipay Language/zh-Hans Region/CN NebulaX/1.0.0 | **AlipayClient** | | Other Alipay+ MPPs, such as TrueMoney Wallet, Touch 'n Go, GCash, DANA, Kakao Pay and AlipayHK | Mozilla/5.0 (Linux; Android 10; Mi 10 Build/QKQ1.191117.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/80.0.3987.99 Mobile Safari/537.36 Ariver/2.16.0 Griver/2.16.2 AppContainer/10.5.10 **AlipayConnect** iapconnectsdk/2.7.0 | **AlipayConnect** | ## Step 3. Initiate a payment After the ACQP decides to route the payment to Alipay+, the ACQP needs to call the **pay** API to place an order with Alipay+. In response, Alipay+ returns _paymentUrl_ to the ACQP, who syncs it to the merchant. With _paymentUrl,_ the merchant redirects the user to the cashier page, where the user confirms the payment ### Processing logic When calling the **pay** API, pay attention to the following things: - Monitor the payment result notifications sent from Alipay+and use the **inquiryPayment** API to proactively query payment results. - The ACQP can prepare a payment result page and configure the page URL in the _paymentRedirectUrl_ parameter, which must be an HTTPS URL. After the user confirms the payment, the user is redirected to this page, where you can display the payment result retrieved from the **notifyPayment** and **inquiryPayment** APIs. ### Sample The ACQP sends a request to Alipay+. ```json { "paymentNotifyUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automation/paymentNotify.htm", "paymentRequestId": "pay_1089760038715669_102775745070000", "paymentFactor": { "isInStorePayment": "true", "isCashierPayment": "true", "inStorePaymentScenario": "EntryCode" }, "order": { "referenceOrderId": "102775745070000", "orderDescription": "SHOES", "orderAmount": { "currency": "JPY", "value": "100" }, "merchant": { "referenceMerchantId": "M00000000001", "merchantName": "UGG", "merchantMCC": "5411", "merchantAddress": { "region": "JP", "city": "xxx" }, "store": { "referenceStoreId": "S00000000001", "storeName": "UGG-2", "storeMCC": "5411" } }, "env": { "userAgent": "Mozilla/5.0 (Linux; Android 9; MI 9 SE Build/PKQ1.181121.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/90.0.4430.66 Mobile Safari/537.36 Language/en Ariver/2.22.0.2 Griver/2.24.0 AppContainer/10.5.10 AlipayConnect AlipayConnect" } }, "settlementStrategy": { "settlementCurrency": "USD" }, "paymentAmount": { "currency": "JPY", "value": "100" }, "paymentMethod": { "paymentMethodType": "CONNECT_WALLET" } } ``` Alipay+ returns a response to the ACQP. ```json { "acquirerId": "2021228100000000", "result": { "resultCode": "PAYMENT_IN_PROCESS", "resultMessage": "The payment in process.", "resultStatus": "U" }, "paymentId": "20190608114010800100188820200350000", "paymentAmount": { "value": "100", "currency": "JPY" }, "paymentUrl": "https://render.alipay.com/p/w/ac-fe-adaptor/?ACCodeValue=281666040098X5mI31LFMzSfInzT2Ts2sO5o&loadingUrl=https%3a%2f%2frender.alipay.com%2fp%2fw%2fac-loading-page%2f" } ``` ### More information For more information about how to use the API (such as the field description), see [pay](../api_acq_tile/pay_entry_code). ## Step 4. 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](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](inquire_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](obtain_payment_results#OJDuS) 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.