Entry code

In the Merchant-presented Mode Payment Entry Code scenario, the Acquiring Partner (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

Before you begin

Before you begin, learn about the following concepts:

• Alipay+ wallet: Refers to Alipay+'s Mobile Payment Partner 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.

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 Partner (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 MPP 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. 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:

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,

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+ MPPs 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 MPPs as shown in the mapping table, 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.

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.