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
• Step 2. Identify the wallet and route the payment
• Step 3. Initiate a payment
• Step 4. Handle the payment result

Workflow

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

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 a merchant page for the user to enter the payment amount. (Step 1-3)
2. After the user enters the payment amount, the merchant sends the order information to the ACQP. (Step 4-5)
3. The ACQP identifies the wallet and decides to route the payment to Alipay+. To do so, the ACQP calls the pay API to place an order with Alipay+. (Step 6-7)
4. After placing the order, Alipay+ returns paymentUrl to the ACQP, who syncs paymentUrl to the merchant. (Step 8-10)
5. With paymentUrl, the merchant redirects the user to the cashier page at the MPP side, where the user confirms the payment. (Step 11-13)
6. 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 14-21)

Step 1. Create an entry code

An entry code is a QR code representing an encoded URL that points to a WAP page. Users can enter a payment amount on this WAP page. The following rules apply:

• Ensure that the WAP page can only be accessed by using the HTTPS protocol.
• On the WAP page, the ACQP needs to provide input fields to collect information such as payment amount.
• Transfer the WAP page address (URL) into a QR code, which is to be printed and presented at the merchants' stores.

Step 2. Identify the wallet and route the payment

After 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 user's wallet by checking the user agent header in the Entry Code WAP page request and then route the payment accordingly.

Note: To ensure the Entry Code WAP page can be opened in Alipay+ supported wallet apps, the ACQP needs to provide the domain name of the WAP page URL to our solution architect.

The following figure illustrates the routing logic:

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 wallet and skip the following steps.
2. If the user agent matches AlipayCN as shown in the mapping table,

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.

3. If the user agent matches other Alipay+ wallets as shown in the mapping table, route the payment to Alipay+ by calling the pay API. For more information, see Step 3. Initiate a payment.
4. If the user agent does not match any wallets as shown in the mapping table, the ACQP can handle the order with its own logic and skip the following steps.

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+.

{
  "paymentNotifyUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/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.

{
  "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.

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.
• 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.

Reference

Terms

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.

Mapping between wallet and user agent string

The following table describes the mapping relationship between a wallet and its user agent string, where

• The Wallet column indicates which wallet the user agent represents.
• The Full User Agent String column contains examples of the user agent (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 a wallet if the string contains the corresponding UA Identifier.