Alipay+ DocsAlipay+ Docs
APIs & SDKs

Order code

In the Merchant-presented Mode Payment Order Code scenario, Alipay+ issues a QR code to the Acquiring Service Provider (ACQP) based on the order information that the merchant collects from the user. The ACQP relays the QR code to the merchant, who 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 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 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 with Alipay+, the merchant confirms the payment amount with the user and selects Alipay+ as the payment method. (Step 1-3)
  2. The merchant sends the order information to the ACQP, which calls the pay API to place an order with Alipay+. (Step 4-5)
  3. After placing the order, Alipay+ generates and returns a QR code to the ACQP, which syncs it to the merchant. The merchant then displays the QR code to the user. (Step 6-10)
  4. After the user scans the QR code, the Mobile Payment Provider (MPP) app sends a request to Alipay+ to decode the QR code. (Step 11-12)
  5. In the decoding result, Alipay+ returns the order information to the MPP app, which then renders the cashier page for the user to confirm the payment. (Step 13-15)
  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 16-23)

Step 1. Initiate a payment

To initiate a payment, the ACQP needs to call the pay API to place an order with Alipay+. In the request, the ACQP needs to pass in the order information that the merchant collects from the user. In response, Alipay+ generates a unique order code based on the order information and returns it in the form of a QR code to the ACQP.

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.

When handling the pay response, pay attention to the following things:

  • If Alipay+ returns the order code, the ACQP needs to sync it to the merchant, who then displays the order code to the user.

Note: The ACQP needs to instruct the merchant to stop displaying the order code in any of the following conditions:

  • The order code is expired.
  • The order is closed by the ACQP before the payment expires.
  • The order is closed by Alipay+.

Sample

The ACQP sends a request to Alipay+.

copy
{
  "paymentNotifyUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
  "paymentRequestId": "pay_1089760038715669_102775745070000",
  "paymentFactor": {
    "isInStorePayment": "true",
    "isCashierPayment": "true",
    "inStorePaymentScenario": "OrderCode"
  },
  "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": {
      "storeTerminalId": "122222",
      "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
    }
  },
  "settlementStrategy": {
    "settlementCurrency": "USD"
  },
  "paymentAmount": {
    "currency": "JPY",
    "value": "100"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET"
  }
}

Alipay+ returns a response to the ACQP.

copy
{
  "acquirerId": "2021228100000000",
  "result": {
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultMessage": "The payment in process.",
    "resultStatus": "U"
  },
  "paymentId": "20190608114010800100188820200350000",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "orderCodeForm": {
    "paymentMethodType": "CONNECT_WALLET",
    "expireTime": "2019-06-01T12:01:01+08:30",
    "codeDetails": [
      {
        "codeValueType": "QRCODE",
        "codeValue": "28166604009zTTyy30WIY7PhnF0czESvxxxx",
        "displayType": "TEXT"
      },
      {
        "codeValueType": "QRCODE",
        "codeValue": "https://qr.alipayplus.com/showQrImage?code=28166604009zTTyy30WIY7PhnF0czESvxxxx&picSize=L",
        "displayType": "BIGIMAGE"
      },
      {
        "codeValueType": "QRCODE",
        "codeValue": "https://qr.alipayplus.com/showQrImage?code=28166604009zTTyy30WIY7PhnF0czESvxxxx&picSize=M",
        "displayType": "MIDDLEIMAGE"
      },
      {
        "codeValueType": "QRCODE",
        "codeValue": "https://qr.alipayplus.com/showQrImage?code=28166604009zTTyy30WIY7PhnF0czESvxxxx&picSize=S",
        "displayType": "SMALLIMAGE"
      }
    ]
  }
}

More information

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

Step 2. 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.

Learn more about

Home
Get Support
Need more help?