Accept a payment

In the User-presented Mode Payment scenario, the merchant scans an Alipay+ payment code that is presented by the user and places an order to the Acquiring Service Provider (ACQP). The ACQP then initiates a payment request to Alipay+. After Alipay+ processed the payment and returns the payment result, the ACQP notifies the merchant of the result.

To accept the payment in this scenario, the ACQP needs to complete the following steps:

• Step 1: Identify the code value and route the payment
• Step 2: Initiate a payment
• Step 3: Handle the payment result

Workflow

The following figure illustrates the workflow of accepting a payment in the User-presented Mode Payment scenario:

Figure 1. Workflow of accepting payments

The payment process consists of the following steps:

1. The merchant scans the user's payment code that is displayed on a Mobile Payment Provider (MPP) app and sends the payment code to the ACQP. (Step 1-3)
2. The ACQP identifies the MPP according to the payment code value and routes the payment to the MPP with the order information. (Step 4)

• If the ACQP directly integrates the MPP, theACQP routes the payment to the MPP and the MPP handles the payment according to its own logic. In this situation, the next steps in this document are not applicable.
• If the ACQP integrates the MPP through Alipay+, the payment is handled according to Alipay+'s logic. In this situation, follow the next steps in this document.

3. The ACQP initiates a payment request and sends the order information to Alipay+ by calling the pay API. (Step 5)
4. Alipay+ initiates a payment request to the MPP with the obtained value of customerId. The MPP then completes and returns the payment result to Alipay+. (Step 6-9)
5. The ACQP receives the payment result from Alipay+ and forwards it to the merchant. (Step 10-11)
6. To ensure the ACQP obtains the payment result, the ACQP can initiate an inquiryPayment request asynchronously. Moreover, Alipay+ calls the notifyPayment API to notify the ACQP of the payment result. (Step 12-18)

Step 1: Identify the code value and route the payment

After collecting an Alipay+ payment code from the merchant, the ACQP needs to identify the code value and route the payment accordingly.

Alipay+ payment codes indicate QR codes that are issued by Alipay+ or Alipay+ MPPs, such as AlipayCN, AlipayHK, GCash, KakaoPay, etc. For more information about the types and rules of Alipay+ payment codes, see Code types and rules.

To identify the code value and route the payment, the ACQP firstly needs to ensure that the merchant scanners support the following two capabilities:

• Recognize all types of Alipay+ payment codes, which are in the length of 16 to 24 digits and start with 25, 26, 27, 28, 29, or 30.
• Preserve the ability of code length expansion. It's recommended that the scanners can support the length of 32 digits for further use.

Moreover, the following section describes the logic of payment routing.

Routing logic

The following figure illustrates the routing logic:

Figure 2. Payment routing logic

The routing logic is explained as follows:

1. If the ACQP integrates Alipay+ and an Alipay+ 19-digit code is identified, route the payment to Alipay+. For the next action, see Step 2.
2. If the ACQP directly integrates AlipayCN or AlipayHK and an AlipayCN or AlipayHK code is identified, route the payment to AlipayCN or AlipayHK. AlipayCN or AlipayHK then handles the payment according to its own logic.
3. If the ACQP directly integrates any other Alipay+ MPP and a CGCP code indicating such an MPP is identified, route the payment to the MPP. The MPP then handles the payment according to its own logic.
4. If the ACQP doesn't directly integrate any Alipay+ MPP and a CGCP code is identified, route the payment to Alipay+. For the next action, see Step 2.

As part of the routing logic, the code identification is processed by using regular expressions. Refer to the table below to learn about the regular expression that is used in each step of the routing logic.

Step 2: Initiate a payment

After deciding to route the payment to Alipay+, the ACQP calls the pay API to send a payment request to Alipay+.

Processing logic

When calling the pay API, take the following things into consideration:

• The following parameters must be specified properly in the request:

• paymentRequestId: indicates the payment order ID. This parameter is used for idempotent control, which requires the ACQP to ensure that for each payment order, a unique value of this parameter needs to be generated and sent in API calls.
• paymentMethod.paymentMethodType: indicates the type of payment method. In the User-presented Mode Payment scenario, specify this parameter as CONNECT_WALLET.
• paymentMethod.paymentMethodId: indicates the unique ID that is assigned by Alipay+ to identify a payment method. In the User-presented Mode Payment scenario, specify this parameter as the value of the payment code that is collected by the merchant from the customer's digital wallet.
• paymentAmount.value: indicates the transaction amount in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, set the value of this parameter to 1. For more information, see ISO 4217 Currency Code.
• paymentExpiryTime: indicates the time after which the payment order is expired. The expiration time by default (Alipay+ expiration time) is 1 minute. The following table shows how the final expiration time varies according to different values of this parameter:

• You might receive different results from Alipay+. Follow the instructions listed in the table below to handle the result.

• In certain cases, if the payment is not completed but needs to be closed from the ACQP side, call the cancelPayment API to close it.

For more information about how to use the pay API, see pay.

Samples

The following sample shows the request and responses when the ACQP calls the pay API from the Alipay+ in the User-presented Mode Payment scenario.

Request from the ACQP to Alipay+

{
    "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": "true",
    "inStorePaymentScenario": "PaymentCode"
    },
    "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": "M00000000001",
            "merchantName": "cup Hu",
            "merchantMCC": "1405",
            "store": {
                "referenceStoreId": "S0000000001",
                "storeName": "UGG-2",
                "storeMcc": "1405"
            },
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      }
        },
    "env":{
        "storeTerminalId":"122222",
      "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
    }
    },
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "paymentAmount": {
        "currency": "JPY",
        "value": "100"
    },
    "paymentMethod": {
        "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "28100602000000000012"
    }
}

Responses from Alipay+ to the ACQP

• For a successful payment (result.resultStaus is S), the response sample is as follows:

{
    "acquirerId": "2021228100000000",
  "pspId": "120120012012",
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    },
    "paymentId": "20190608114010800100188820200355883",
    "paymentAmount": {
        "value": "100",
        "currency": "JPY"
    },
   "paymentTime": "2021-04-08T14:48:50+08:00",
  "customerId": "208812211212001",
  "walletBrandName":"KAKAOPAY"
}

• For a failed payment (result.resultStatus is F), the response sample is as follows:

{
   "result": {
       "resultCode": "PROCESS_FAIL",
       "resultMessage": "A general business failure occurred. Don't retry.",
       "resultStatus": "F"
   }
}

• For a payment with an unknown payment status (result.resultStatus is U), the response sample is as follows:

{
   "result": {
       "resultCode": "UNKNOWN_EXCEPTION",
       "resultMessage": "API failed due to unknown reason.",
       "resultStatus": "U"
   }
}

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 Alipay+:

• notifyPayment: This API is used by Alipay+ to notify the Alipay+ 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 User-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.