Make a payment

Alipay+ provides a set of APIs and a server SDK for the Mobile Payment Provider (MPP) to implement the capability of making a payment in the following scenarios:

Scenario 1: After placing an order, the user is redirected to the cashier page that is rendered in the MPP's app, WAP, or Web terminal to pay.
Scenario 2: After placing an order on the merchant Web page, the user scans the order code with the MPP's app and then is redirected to the cashier page that is rendered in the MPP's Web terminal to pay.

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

Step 1: Identify the code
Step 2: Decode the code
Step 3: Render and present the cashier page
Step 4: Return the payment result
(Optional) Step 5: Redirect the user back to the merchant page

Workflow

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

Cashier Payment.png

Figure 1. Workflow of making a payment

Notes:
Figure 1 illustrates the payment flow of Scenario 1. For Scenario 2, there is one more step between Step 4 and Step 5, in which the user scans the order code with the MPP's app.
If the MPP does not provide an app, the MPP must provide the capability of redirecting users to a Web/WAP wallet page; otherwise, this capability can be used as a relegation option. The MPP needs to provide the Web/WAP implementation of the app for the merchant to redirect users to. For more information about redirection, see Guide on redirections between the merchant and the Mobile Payment Partner.

The payment process consists of the following steps:

After placing an order, the user chooses a payment method. The ACQP then sends a payment request to Alipay+. (Step1-2)
Alipay+ generates an order code value to append to the MPP cashier URL. (Step 3)
Alipay+ returns the MPP cashier URL to the merchant with the order code value. (Step 4)
The merchant redirects the user to the MPP cashier page with the order code value. (Step 5)
The MPP client forwards the order code value to the MPP server for code identification. (Step 6)
The MPP server identifies whether the order code is supported by Alipay+ in either of the following ways: (Step 7-9)

The MPP server calls the Alipay+ server SDK. The Alipay+ server SDK returns the code identification result via the CodeIdentificationService.identifyCode API.
The MPP server calls the inquiryCodeRules API to obtain the Alipay+ code rules and save them locally. When receiving the order code value from the MPP client, the MPP server directly uses the code rules for code identification.

The MPP server initiates a decoding request via the userInitiatedPay API. Alipay+ returns the order information to the MPP server. (Step 10-11)
The MPP server forwards the order information to the MPP client. (Step 12)
The MPP client displays the cashier page, where the user confirms and completes the payment. (Step 13-15)
The MPP server notifies Alipay+ of the payment result via the notifyPayment API. Alipay+ then notifies the merchant/Acquiring Service Provider (ACQP) of the payment result. (Step 16-17)
The MPP server returns the payment result to the MPP client and the MPP client displays the payment result page to the user. (Step 18-19)
(Optional) If the paymentRedirectURL parameter is returned by Alipay+ in the userInitiatedPay API, the MPP redirects the user back to the merchant payment result page. (Step 20-21)

Step 1: Identify the code

When receiving the order code value from Alipay+, the MPP server needs to identify the order code. The following figure illustrates the process of code identification:

12_make a payment.png

Figure 2. Process of code identification

The process consists of the following steps:

The MPP server determines whether the order code is an MPP local code. If so, the MPP server processes the code according to its own logic; otherwise, take the next step.
The MPP server identifies whether the order code is supported by Alipay+ with either of the following methods:

Call the Alipay+ server SDK APIs. For more information, see Use the Alipay+ server SDK.
Obtain the Alipay+ code rules and use them locally. For more information, see Use the Alipay+ code rules locally.

For different code identification results, take different actions as follows:

If the order code is supported by Alipay+, the MPP server requests Alipay+ to decode. For more information, see Step 2.
Otherwise, the MPP processes the code according to its own logic.

Step 2: Decode the code

Once the code is identified as an Alipay+ code, the MPP sends a userInitiatedPay request to Alipay+ for decoding. Alipay+ then returns the order information to the MPP in the response.

Processing logic

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

Ensure the following parameters are configured properly in the request:

codeValue: indicates the order code value that is obtained by the MPP client.
customerId: indicates the unique ID that is assigned by the MPP to identify a user.

Handle the response properly, especially the following parameters:

order: indicates the order information that is agreed upon by the user and the merchant. This information is used to render and display the cashier page in the MPP's terminal. For more information, see Step 3.
paymentRedirectURL: indicates the URL where the user is redirected after the payment is completed. If this parameter is returned, the MPP needs to redirect the user back to the merchant side. For more information, see Step 4.
result: indicates the decoding result. The MPP might receive different results from Alipay+. Follow the instructions below to handle the result.

result.resultStatus	result.resultCode	Decoding status	Actions
`S`	`SUCCESS`	Decoding succeeds.	Guide the user to confirm the payment.
`F`	Multiple possible values exist, such as `ACCESS_DENIED`, `BUSINESS_NOT_SUPPORT`, etc.	Decoding fails.	Take actions according to the result code (specified in the result.resultCode parameter). For more information, see the Result code section in the userInitiatedPay API.
`U`	Multiple possible values exist, such as `REQUEST_TRAFFIC_EXCEED_LIMIT`, `UNKNOWN_EXCEPTION`, etc.	Decoding is in processing.	Retry the same request.
No result received		Unknown	Retry the same request.

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

Sample

The following samples show the request and response when the MPP calls the Alipay+ userInitiatedPay API in the Cashier Payment scenario.

Request from the MPP to Alipay+

copy
{
  "codeValue":"http://xxxxx/281xxxxxxxxxxxxxxxx4441",
  "customerId":"208800000000000001"
}

Response from Alipay+ to the MPP

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "acquirerId": "1020000000000000001",
  "pspId": "1020000000000000001",
  "order": {
    "referenceOrderId": "OrderID_0101010101",
    "orderDescription": "SHOES",
    "orderAmount": {
      "value": "100",
      "currency": "JPY"
    },
    "merchant": {
      "referenceMerchantId": "M00000000001",
      "merchantMCC": "5411",
      "merchantName": "UGG",
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      }
    }
  },
  "codeType": "ORDER_CODE",
  "paymentRequestId": "20200000000000000133",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "payToAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "paymentQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice": "10.0000"
  },
  "paymentPromoInfo": {
    "paymentPromoDetails": [
      {
        "promoId": "discount_id_1",
        "promoType": "INSTANT_DISCOUNT",
        "promoName": "10 JPY off 100 JPY",
        "savingsAmount": {
          "value": "100",
          "currency": "KRW"
        }
      }
    ]
  },
  "paymentFactor": {
    "isCashierPayment": "true",
    "isInStorePayment": "false"
  }
}

Step 3: Render and display the cashier page

With the order information that is returned from Alipay+ in Step 2, the MPP renders and displays the cashier page to the user. Then, The user confirms the information and completes the payment on the cashier page. For references on how to design the cashier page, see Payment confirmation page.

Step 4: Return the payment result

After the payment is processed, the MPP needs to inform both the user and Alipay+ of the payment result by taking the following actions:

Display the Payment Result Page to the user in the MPP app. For how to design the payment result page, see Payment Result Page.
Return the payment result to Alipay+ in the request of notifyPayment API or the response of the inquiryPayment API. For more information, see Return payment results.

Step 5: Redirect the user back to the merchant side

If the paymentRedirectURL parameter is returned by Alipay+ in the userInitiatedPay API response, the MPP needs to redirect the user back to the merchant side. Then, the merchant presents a payment result page to the user.

When implementing the capability of redirection back, apply the following rules:

Once the payment is completed, the MPP needs to redirect the user back to the merchant side, unless the user scans the order code to pay. In the latter case, it is recommended to redirect the user back to the homepage of the MPP app.
The MPP needs to trust all URLs that are involved in Alipay+ transactions so that the user redirection to the merchant side will not be blocked.
The MPP needs to support the user redirection to the merchant side no matter whether the merchant provides a WAP page URL, URL scheme, App Link, or Universal Link.
For the app terminal, if you allow the user to cancel a payment via a payment cancellation button, it is recommended you redirect the user back to the merchant side automatically after the cancellation succeeds; otherwise, the user has to return to the merchant side manually.