Alipay+ provides a set of APIs for Mobile Payment Providers (MPPs) to implement the capability of making a payment in the scenario where a user uses an MPP app to present a payment code to the merchant.

To make a payment, the MPP needs to take the following steps:

• Step 1: Obtain logos of acceptance marks and payment code
• Step 2: Render and present the payment code
• Step 3: Process the payment request
• Step 4: Return the payment result

Workflow

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

Figure 1: Payment workflow

The payment process consists of the following steps:

1. The user opens the Payment Code page in the MPP app (Step 1).
2. The MPP app calls the getAcceptanceMarkLogos API from Alipay+ Client SDK to obtain the logos of acceptance marks (Step 2).
3. The MPP app obtains the logos of acceptance marks and displays them on the Payment Code page (Steps 3-4).
4. When the user opens the payment code page, the MPP app also initiates a request for a payment code (step 5).
5. The MPP app requests the payment code from the MPP server. The MPP server then calls the getPaymentCode API to request the payment code from Alipay+ (Steps 6-7).
6. Alipay+ returns the payment code to the MPP server, which then sends the payment code to the MPP app (Steps 8-9).
7. The MPP app displays the payment code on the payment code page (Step 10).
8. The merchant scans the payment code and initiates a payment by sending the payment code and the payment information to Alipay+ via the ACQP (Steps 11-13).
9. Alipay+ decodes the payment code to obtain the MPP user ID and calls the pay API to send the payment request to the MPP server (Steps 14-15).
10. The MPP server processes the payment and returns the payment result to Alipay+ (Steps 16-17).
11. Alipay+ returns the payment result to the ACQP. The ACQP then returns the payment result to the merchant (Steps 18-19).
12. The MPP server informs the MPP app of the payment result. The MPP app then renders and displays the payment result page to the user (Steps 20-21).

Step 1: Obtain logos of acceptance marks and payment code

To render the payment code page, the MPP needs to obtain both the logos of the acceptance marks and the payment code.

Obtain logos of acceptance marks

To obtain the logos of the acceptance marks, the MPP client needs to call the getAcceptanceMarkLogos API from Alipay+ Client SDK. The following figure illustrates the workflow of obtaining logos of acceptance marks.

Figure 2. The workflow of obtaining logos of acceptance marks

The process of obtaining the logos of acceptance marks consists of the following steps:

1. The user opens the Payment Code page in the MPP app (Step 1).
2. The MPP app calls the getAcceptanceMarkLogos API from Alipay+ Client SDK to obtain the logos of acceptance marks. The MPP can determine whether to pass in the region parameter in the API request (Step 2).
3. (Optional) If the configuration information is not cached locally or if more than 24 hours have elapsed since Alipay+ Client SDK last pulls the configuration information, Alipay+ Client SDK calls the fetchConfig API to obtain the configuration information from the Alipay+ server (Steps 3-4).
4. The MPP app obtains the logos of acceptance marks in either of the following ways: (Steps 5-9)

• If the region parameter is not passed in by the MPP, Alipay+ Client SDK determines the user's current location based on the cellular service provider information and/or the time zone obtained from the MPP app. Alipay+ Client SDK then retrieves the logos of acceptance marks from the configuration information and returns them to the MPP app.
• If the region parameter is passed in by the MPP, Alipay+ Client SDK directly obtains the logos of acceptance marks from the configuration information and returns them to the MPP app. For best practices about how to obtain location information from the user's mobile device, see Obtain location information.

Note:

• If Alipay+ is not supported in the user's current location, Alipay+ Client SDK returns an empty array.
• Since the Alipay+ logo is mandatory to be displayed on the Payment Code page, the MPP needs to configure the Alipay+ logo in advance and Alipay+ Client SDK does NOT return the Alipay+ logo.

5. The MPP app displays the logos of acceptance marks accordingly on the Payment Code page (Step 10).

Obtain the payment code

While the MPP app obtains the logos of the acceptance marks, the MPP server also calls the getPaymentCode API to obtain the payment code from Alipay+.

Processing logic

When using the getPaymentCode API, take the following things into consideration:

• Ensure the following parameters are configured properly in the request:

• customerId: indicates the MPP user ID, which is required by Alipay+ for the payment code generation.
• codeQuantity: the number of payment codes to be sent to the MPP. The default value of this parameter is 1. The MPP can specify this parameter to obtain multiple payment codes at a time. The MPP can cache the additional payment codes, and display a new payment code in case a previous one is expired, as the default validity period of a payment code is only 1 minute.
• env.deviceTokenId: indicates the token ID of the user's device. This parameter is required and used by Alipay+ for risk control. For more information about the value of this parameter and how to obtain it, see Obtain the device token ID.

• Handle the response properly, especially the following parameters:

• paymentCodeInfoList: a list of payment codes. The quantity of the payment codes is determined by the value of the codeQuantity parameter in the request.
• result: the result of the payment code application. The MPP might receive different results from Alipay+. Follow the instructions below to handle the result.

Sample

The following samples show the request and response when the MPP calls the Alipay+ getPaymentCode API in the User-presented Mode Payment scenario.

Request from the MPP to Alipay+

{
  "region": "PH",
  "customerId": "21281****",
  "codeQuantity": "3",
  "env": {
    "deviceTokenId": "21212****"
  }
}

Response from Alipay+ to the MPP

{
  "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    },
  "paymentCodeInfoList": [{
    "paymentCode": "2892889331822611998",
    "codeValidityStartTime": "2024-01-16T15:19:20+08:00",
    "codeExpiryTime": "2024-01-16T15:20:20+08:00"
  }, {
    "paymentCode": "2892889221822611928",
    "codeValidityStartTime": "2024-01-16T15:19:50+08:00",
    "codeExpiryTime": "2024-01-16T15:20:50+08:00"
  }, {
    "paymentCode": "2892889441822611221",
    "codeValidityStartTime": "2024-01-16T15:20:20+08:00",
    "codeExpiryTime": "2024-01-16T15:21:20+08:00"
  }]
}

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

Step 2: Render and display the payment code

After receiving the payment code in the response from Alipay+ getPaymentCode API, the MPP app renders and presents the payment code on the payment code page. The merchant can then scan the payment code to initiate a payment request. For more information about the requirements on the Payment Code page, see User-presented Mode Payment.

Step 3: Process the payment

After the merchant scans the payment code, Alipay+ sends the payment request to the MPP by using the pay interface. The MPP then processes the payment request.

Processing logic

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

• Handle the request properly, especially the following parameters:

• payToAmount: the amount that Mobile Payment Provider settles to Alipay+ in Mobile Payment Provider's currency. By default, the amount that the user actually pays is specified by this parameter.
• currency: the MPP must be able to handle the requests made with currencies in ISO 4217.
• paymentMethod: indicates the payment method that is used to collect the payment. The following rules apply:

• paymentMethod.paymentMethodType: indicates the payment method. The value of this parameter is fixed as CONNECT_WALLET.
• paymentMethod.paymentMethodId: indicates the payment code value. The value of this parameter is the same as that of the paymentCode parameter from the getPaymentCode API.
• paymentMethod.customerId: indicates the MPP user ID. This parameter is required and the MPP must be able to handle payment requests with the specified user ID.

• paymentExpiryTime: indicates when the payment times out. For User-presented Mode Payment, the payment times out in 1 minute by default.

• Ensure the following parameters are configured properly in the response:

• result: indicates the payment result. The MPP must be able to synchronously return the payment result by using this parameter.

• result.resultCode: The following table shows how to set the value of the result.resultCode parameter under different conditions.

Sample

The following samples show the request and response when Alipay+ calls the pay API in the User-presented Mode Payment scenario.

Request from Alipay+ to the MPP

{
  "order": {
    "referenceOrderId": "OrderID_010101****",
    "orderDescription": "SHOES",
    "orderAmount": {
      "value": "100",
      "currency": "JPY"
    },
    "merchant": {
      "referenceMerchantId": "M00xxxxx0001",
      "merchantMCC": "5411",
      "merchantName": "UGG",
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      },
      "store": {
        "referenceStoreId": "S00xxxx0001",
        "storeName": "UGG-2",
        "storeMCC": "5411"
      }
    }
  },
  "acquirerId": "102218800000000****",
  "pspId": "102217200000000****",
  "paymentRequestId": "201811291907410100070000007****",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "281006050000000000125733DAHJ****",
    "customerId":"2160xxxxxxxxxxx1"
  },
  "payToAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "paymentQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice": "10.0000"
  },
  "paymentFactor": {
    "isInStorePayment": "true"
  }
}

Response from the MPP to Alipay+

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
 },
 "paymentId":"201xxxxxxxxxxxxxxxxxxxxxxx4444",
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "customerId":"1234567"
}

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

Step 4: Return the payment result

After the payment is processed, the MPP must inform the user and Alipay+ of the payment result.

• To the user, display the payment result page in the MPP app. For references on how to design the payment result page, see Payment result page.
• To Alipay+, return the payment result in the pay API response. Also, use the inquirePayment and the notifyPayment APIs to send the payment result. See Return the payment result for details.