Alipay+ DocsAlipay+ Docs

Accept a payment

To integrate Alipay+ Merchant-presented Mode Payment (Push Mode), the Acquiring Service Provider (ACQP) needs to complete the following steps:

Workflow

The following figure illustrates the workflow of accepting a payment in the Merchant-presented Mode Payment scenario (Push Mode).

image.png

Figure 1. Workflow of accepting a payment

The payment process consists of the following steps:

  1. The merchant displays the QR code to the user. (Step 1)
  2. After the user scans the QR code, the Mobile Payment Provider (MPP) app identifies the QR code and proceeds according to the code type as follows: (Steps 2-3)
    • If the code is identified as an entry code of the ACQP:
      1. The MPP app redirects the user to the Alipay+ payment amount input page and sends Alipay+ the code value which is appended to the page URL. (Step 4)
      2. Alipay+ calls the userInitiatedPay API to send a decoding request to the ACQP and obtains the merchant information. (Steps 5-8)
      3. The user inputs the payment amount on the page to generate an order and is redirected to the MPP app. (Steps 9-10)
    • If the code is identified as a private order code of the ACQP:
      1. The MPP app sends a request to Alipay+ to decode the QR code. (Step 11)
      2. Alipay+ calls the userInitiatedPay API to send a decoding request to the ACQP and obtains the order information. (Steps 12-15)
  1. The MPP app displays the order information for the user to confirm the payment. (Steps 16-17)
  2. The MPP makes the payment and notifies Alipay+ of the payment result. After Alipay+ acknowledges the payment result, the MPP app displays the payment result to the user. (Steps 18-21)
  3. Alipay+ calls the pushPayment API to push the payment to the ACQP, requesting to accept the payment on the ACQP side. (Steps 22-24)
  4. The ACQP returns the final payment result to Alipay+ through the inquiryPushPayment or notifyPushPayment API. (Steps 25-28)
  5. If the ACQP failed to accept the payment, Alipay+ informs the MPP to cancel the payment and refund to the user. (Steps 29-32)

Step 1. Create a QR code

The ACQP creates one of the following two QR codes according to the payment scenario and displays it to the user.

Entry code

An entry code is a static QR code that represents the merchant. The ACQP needs to keep the merchant details in the ACQP system.

To ensure that the entry code can be identified by Alipay+-supported wallets as an entry code of the ACQP, the ACQP needs to provide rules on how to identify the entry code to the Alipay+ Solution Architect.

Private order code

A private order code is a dynamic QR code that represents the order. The ACQP needs to create a unique QR code for each order submitted by the merchant and keep the order details in the ACQP system.

To ensure that the private order code can be identified by Alipay+-supported wallets as a private order code of the ACQP, the ACQP needs to provide rules on how to identify the private order code to the Alipay+ Solution Architect.

More information

For more requirements on the QR codes, see QR code standards.

Step 2. Handle the userInitiatedPay request

After receiving the value of the code that the user scans from the MPP, Alipay+ sends a decoding request to the ACQP by calling the userInitiatedPay API.

When receiving the userInitiatedPay request from Alipay+, the ACQP handles the request as follows:

  1. Decode the QR code to obtain the merchant/order information.
  2. Check if the code and the merchant/order are valid.

Note: Because the MPP makes the payment first and then the ACQP accepts the payment in the Push Mode. If the ACQP fails to accept the payment, the MPP has to refund to the user. For a better user experience, the ACQP must validate the code and the merchant/order to minimize the likelihood of refunds.

  1. Return the merchant/order details to Alipay+ in response to the userInitiatedPay request.

Processing logic

In the private order code scenario, when handling the userInitiatedPay request, you can choose either of the following schemes regarding multiple payments for the same order code (specified on the codeValue parameter) and take the corresponding action:

Scheme

Action required

Allow multiple payments for a single order code.

After decoding the same order code, return different paymentRequestId values.

Do not allow multiple payments for a single order code.

After decoding the same order code, return the same paymentRequestId value.

Thus, Alipay+ only processes the first payment request with the same paymentRequestId value.

Sample

Alipay+ sends a userInitiatedPay request to the ACQP.

copy
{
  "acquirerId": "2021228100000000",
  "pspId": "1022172000000000000",
  "codeValue": "http://a.com/2810060438884961634",
  "customerId": "208812211210000"
}

The ACQP returns a response to Alipay+.

  • In the entry code scenario:
copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    },
    "codeType": "STORE_CODE",
    "merchant": {
        "referenceMerchantId": "M0000000001",
        "merchantMCC": "5411",
        "merchantName": "UGG",
        "store": {
            "referenceStoreId": "S000000001",
            "storeName": "UGG-2",
            "storeMCC": "5411"
        },
        "merchantAddress": {
            "region": "JP",
            "city": "xxx"
        }
    },
  "indirectAcquirer":{
    "referenceAcquirerId": "2112211212",
    "acquirerName": "UGG",
    "acquirerAddress": {
            "region": "JP",
            "city": "xxx"
        }
  },
    "paymentCurrency": "MYR",
    "paymentRequestId": "20200101234567890000",
    "paymentAmount": {
        "value": "100",
        "currency": "JPY"
    },
    "paymentFactor": {
        "isInStorePayment": "true",
        "isCashierPayment": "true",
        "inStorePaymentScenario": "EntryCode"
    },
    "settlementStrategy": {
        "settlementCurrency": "USD"
    }
}
  • In the private order scenario:
copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "codeType": "ORDER_CODE",
  "order": {
    "referenceOrderId": "OrderID_010101001",
    "orderDescription": "SHOES",
    "orderAmount": {
      "value": "100",
      "currency": "JPY"
    },
    "merchant": {
      "referenceMerchantId": "M0000000001",
      "merchantMCC": "5411",
      "merchantName": "UGG",
      "store": {
        "referenceStoreId": "S000000001",
        "storeName": "UGG-2",
        "storeMCC": "5411"
      },
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      }
    },
    "indirectAcquirer":{
      "referenceAcquirerId": "2112211212",
      "acquirerName": "UGG",
      "acquirerAddress": {
            "region": "JP",
            "city": "xxx"
        }
    },
    "env": {
      "storeTerminalId": "122222",
      "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
    }
  },
  "paymentRequestId": "20200101234567890000",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "paymentFactor": {
    "isInStorePayment": "true",
    "isCashierPayment": "true",
    "inStorePaymentScenario": "OrderCode"
  },
  "settlementStrategy": {
    "settlementCurrency": "USD"
  }
}

More information

For more information about how to use the API, see userInitiatedPay (entry code) or userInitiatedPay (private order code).

Step 3. Handle the pushPayment request

After receiving the payment result of success from the MPP, Alipay+ pushes the payment to the ACQP by calling the pushPayment API, requesting to accept the payment on the ACQP side.

When receiving the pushPayment request from Alipay+, the ACQP handles the request as follows:

  1. Process the payment in the ACQP system.
  2. Return the payment result to Alipay+ and synchronize the payment result to the merchant.
    Alipay+ provides the inquiryPushPayment and notifyPushPayment APIs for the ACQP to return the payment result. For more information, see Return the payment result.

To ensure consistent payment results on the ACQP and MPP sides, after receiving the payment result from the ACQP, Alipay+ handles the result as follows:

  • If the ACQP accepts the payment, the payment is made successfully.
  • If the ACQP failed to accept the payment, the payment failed. Alipay+ informs the MPP to cancel the payment and refund to the user.

Note: Under the premise that the ACQP validates the code and the merchant/order when handling the userInitiatedPay request, the payment success rate needs to exceed 99%.

Processing logic

The paymentId parameter in the pushPayment API is an idempotency field.

When handling the pushPayment request, if multiple requests with the same paymentId are received, regard the requests as repeated and process the requests only once.

Note: In addition, you need to consistently follow the processing logic outlined in Processing logic for handling the userInitiatedPay request throughout the entire process.

Sample

Alipay+ sends a pushPayment request to the ACQP.

copy
{
  "acquirerId": "1020000000000000001",
  "pspId": "1020000000000000001",
  "paymentRequestId": "2010000000000000000000000007771",
  "paymentId": "2010000000000000000000000007771",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "settlementAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "customerId": "1230000",
  "walletBrandName": "walletName",
  "paymentTime": "2020-01-01T12:01:01+08:00",
  "mppPaymentId": "pay_1089760038715670_102775745070001",
  "codeValue": "00020201021126580014A000000615000101065887340212MBBQR1666203031000000000005204729853034585802MY5915RUMAHSIHATKIT"
}

The ACQP returns a response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentRequestId":"2010000000000000000000000007771",
  "paymentTime":"2020-01-01T12:01:01+08:00"
}

More information

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

Learn more about

Home
Get Support
Need more help?