To accept a payment after the user places an order, the Acquiring Service Provider (ACQP) needs to take the following steps:

1. Render the payment method page
2. Initiate a payment
3. Handle the payment result

Before you begin

Different ACQPs offer varying service models. For example:

• Some provide end-to-end integration, delivering both client-side and server-side components as a unified solution.
• Others provide server-side capabilities only, requiring merchants to integrate the Alipay+ client side independently.

Note: Throughout this documentation, “your client side” and “your server side” refer to the corresponding components in your integration, regardless of your service model.

Workflow

The following figure illustrates the workflow of accepting a payment in the Cashier Payment scenario.

The payment process consists of the following steps:

1. The user selects a payment method to make a payment. (Step 1)
2. Your client side calls your server side to initiate a payment. Then your server side calls the pay API to submit the order to Alipay+. Alipay+ then returns the payment URL (and code) to your server side, which forwards it to your client side. (Steps 2-5)

Note: If the merchant platform is a desktop website and the selected wallet supports code scanning, Alipay+ also returns a QR code value. The merchant can either render the code locally or redirect the user to the Alipay+ cashier page, where the code is displayed by Alipay+.

4. Using the payment URL (and code), your client side redirects the user to the MPP's payment confirmation page, where the user confirms and completes the payment. (Steps 6-8)
5. After the user completes the payment at the MPP side, Alipay+ notifies your server side of the payment result, which is then forwarded to your client side. Your server side can also asynchronously call the inquiryPayment API to retrieve the payment status. (Steps 9-15)
6. Your client side displays the payment result to the user. (Steps 16-17)

Step 1: Render the payment method page

Note: To obtain the available wallet information, you can:

• Call the consultPayment API to receive information about payment methods, including wallet logos.
• Call the inquiryRegistrationStatus API to retrieve the merchant registration result. For Alipay+ brand logo images, use the Acceptance Mark Generator to download the approved assets. For the correct brand name text, refer to the Brand name list.

Follow the steps below to retrieve available payment methods and render the payment method page:

1. Alipay+ returns a response that includes the following information:

• Alipay+ brand name and logo, which is specified in the paymentOptions parameter.
• The wallet name and logo, which are specified in the paymentOptions.paymentOptionDetail parameter.
• The wallet payment ability, which is specified in the supportCodeScan parameter.

• If the value is true, the wallet supports code-scanning. The merchant can choose to render the order code by itself or by Alipay+.
• Otherwise, the wallet does not support code-scanning. The user is redirected to the wallet login page.

2. Your client-side renders the payment method page (also named as "merchant's cashier page") by using the Alipay+ and wallet brand information that is returned in Step 1.

Step 2: Initiate a payment

1. Integrate the pay API

The ACQP needs to integrate the pay API provided by Alipay+. Refer to the following section to learn about how to configure the key request parameters and handle the response parameters.

The following figure illustrates the flow of initiating a payment:

1. Your server side calls the pay API with the following parameters. (Step 2)

• paymentMethodType that specifies the payment method.
• terminalType that specifies the terminal type of your client side.
• Other parameters as required. For more information, see the pay API specification.

2. Alipay+ returns the URL (and code) of the wallet payment confirmation page. (Step 3)

Note: In the Cashier Payment - Web scenario, if the wallet supports code scanning, Alipay+ also returns the codeValue parameter. The merchant can use this value to render the order QR code on its PC website. The QR code expires at the same time as the payment.

It is recommended that the merchant prompt the user to complete the payment before expiration. You can refer to the Alipay+ UX designs for instructions on rendering the QR code.

Processing logic

When calling the pay API, consider the following things:

1. Ensure the following parameters are configured properly in the request:

• paymentExpireTime: Specifies the order timeout time. The following table lists the detailed information about this parameter:

• order.env.terminalType and request.order.env.osType: Specify the type of your client side's terminal and operating system where the user initiates the request. The following table lists the detailed information about these two parameters:

Note: For terminalType and osType, do not specify the type of the terminal or the operating system of the wallet that the merchant wants to trigger.

• paymentRedirectUrl: Specifies the address of your client side where the user is redirected after the user proceeds with the payment order to a status of success, failure or unknown (for example, give up the payment order). The following table lists the detailed information about this parameter:

Note: In certain cases, the user may not be automatically redirected back to your client side after the payment. Therefore, your client side needs to call your server side to query the payment result.

• paymentNotifyUrl: Specifies the address of your server side where the payment result is returned after the payment is completed. For security reasons, the address must be an HTTPS address instead of an HTTP address.
• paymentFactor.presentmentMode: Specifies the presentment mode. In this scenario, the value must be set to TILE.

2. Handle the request properly, especially the following parameters:

• normalUrl, schemeUrl and applinkUrl: Specifies the payment URL of the wallet payment confirmation page. Depending on the capabilities of the wallet, Alipay+ returns one or some of the three parameters.
• You might receive different results from Alipay+, follow the instructions below to handle the result:

Note: If the user has completed the payment successfully and you invoke the pay API again with the same parameters, the resultStatus parameter is returned as S.

Sample

The ACQP sends request to Alipay+.

{
  "userRegion": "PH",
  "allowedPspRegions": ["MY", "PH"],
    "paymentExpiryTime": "2019-06-01T12:01:01+08:30",
    "paymentNotifyUrl": "http://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
    "paymentRequestId": "pay_1089760038715669_102775745075669",
    "paymentFactor": {
        "isInStorePayment": "false",
        "isCashierPayment": "true"
    },
    "order": {
        "referenceOrderId": "102775745075669",
        "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3 ",
        "orderAmount": {
            "currency": "JPY",
            "value": "100"
        },
        "merchant": {
            "referenceMerchantId": "M0000000001",
            "merchantName": "cup Hu",
            "merchantMCC": "1234",
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      }
        },
    "env":{
       "terminalType":"APP",
       "OsType":"IOS"
    }
    },
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "paymentAmount": {
        "currency": "JPY",
        "value": "100"
    },
    "paymentMethod": {
        "paymentMethodType": "TRUEMONEY"
    }
}

Alipay+ returns a response to the ACQP.

{
  "acquirerId": "202122810000****",
  "result": {
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultStatus": "U",
    "resultMessage": "The payment in process."
  },
  "paymentId": "2019060811401080010018882020035****",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "appLinkUrl": "http://iopengw-sea.com/api/open/v1/ac/cashier/self/codevalue/checkout.htm?codeValue=https%3A%2F%2Fqr.alipayplus.com%2F281666040092tUox5AICEzTlESzUJe26IPnn",
  "orderCodeForm": {
    "paymentMethodType": "walletName",
    "expireTime": "2019-06-01T12:01:01+08:30",
    "codeDetails": [
      {
        "codeValueType": "QRCODE",
        "codeValue": "https://qr.alipay.com/bavh4wjlxf12tper3b",
        "displayType": "TEXT"
      },
      {
        "codeValueType": "QRCODE",
        "codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F281002040011kGko31tPT30V6G9hJiH8YNMa&picSize=L",
        "displayType": "BIGIMAGE"
      },
      {
        "codeValueType": "QRCODE",
        "codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F281002040011kGko31tPT30V6G9hJiH8YNMa&picSize=M",
        "displayType": "MIDDLEIMAGE"
      },
      {
        "codeValueType": "QRCODE",
        "codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F281002040011kGko31tPT30V6G9hJiH8YNMa&picSize=S",
        "displayType": "SMALLIMAGE"
      }
    ]
  },
         "paymentData": "***"
}

More information

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

2. Redirect the user to wallet

After your server side handles the pay API response successfully, your client side needs to redirect the user to the payment confirmation page on the MPP side, where the user can confirm the payment.

The following figure illustrates the flow of redirecting the user to the wallet.

1. With the parameters of normalUrl, schemeUrl, or applinkUrl returned in the response of the pay API, your client side redirects the user to the wallet payment confirmation page. (Step 1)
2. Before the order times out, the user confirms the payment in the wallet, and then the order is completed. (Steps 2-3)
3. If the user fails to complete the payment, they can retry in the wallet until the order times out. (Step 2.1)
4. The wallet directs the user to your client side if the payment is successful. (Step 4)

Client-side redirection capabilities are different depending on your client-side and wallet-side terminal type. Your client side must use the payment URL specified in the normalUrl, schemeUrl, or applinkUrl parameter in the pay API response to redirect the user to the wallet side. For more information about the redirection, see Guide on redirections between the merchant and the digital wallet.

Recommendation for Web terminals:If the terminal type of your client side is Web, open a new tab for the user when the user is redirected to the wallet payment confirmation page from the merchant page. This provides the following benefits:

• Allows users to easily switch back if the page fails to load, instead of relying on the back button, which usually fails.
• Enables you to add a confirmation dialog on the merchant page to verify the payment result if the MPP fails to redirect the user back after the payment. For more information, see Add a confirmation dialogue.

3. Handle the redirection from the wallet

After the user proceeds with the payment order to a status of success, failure, or unknown (for example, giving up the payment order), the MPP can redirect the user to a predetermined page on your side, for example, the merchant payment result page. The URL of the predetermined page is specified on the paymentRedirectUrl parameter of the pay API. When rendering the payment result page, you need to ensure the latest payment result is displayed. To obtain the latest payment result, you can receive the notifyPayment API call or call the inquiryPayment API from Alipay+. For more information about how to obtain payment results, see Handle the payment result.

(Recommended) Add a confirmation dialogue

A confirmation dialog after the user is redirected to the MPP client helps users confirm the payment result even when the MPP fails to redirect them back to your side.

Note: If the MPP client opens the redirect URL successfully, dismiss the confirmation dialogue.

The following figure shows an example of a confirmation dialog.

After the user clicks the button according to the actual payment result on the MPP side, the user is redirected to the merchant payment result page after the latest payment result is returned to your server side.

Step 3: Handle the payment result

To ensure that your server side 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 the ACQP 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 Cashier Payment scenario, both APIs must be implemented to work together and ensure an accurate final payment status.

See the Collaboration between inquiryPayment and notifyPayment section for guidance on handling results from both APIs.