Accept a payment

After the user places an order, the Acquiring Service Provider (ACQP) must take the following integration steps to enable the user to complete the payment:

Step 1: Render the payment method page

Step 2: Initiate a payment

Step 3: Handle the payment result

Before you begin

Different ACQPs provide different service modes, for example:

• some ACQPs provide the payment capability to merchants by packaging the client side and the server side into an integrated service.
• some ACQPs only provide the server side ability, while merchants are required to integrate the Alipay+ client side.

Therefore, for the convenience of developers to read this document, no matter which service mode is used, "your client side" and "your server side" are used uniformly to refer to the corresponding client side and server side in different service mode.

Workflow

The following figure illustrates the main workflow of Cashier Payment, which focuses on how to accept a payment.

Figure 1. Workflow of accepting a payment

Note: the payment method page mentioned in Figure 1 is also known as merchant's cashier page.

The payment process consists of the following steps:

1. After a user places an order on the merchant platform, your client side renders the payment method page in the following two steps: (Step 1-7)

1.1 Your client side consults the information about Alipay+ payment method.

1.2 Your client side renders the payment method page with the information that is obtained in the previous step.

2. After the user chooses the Alipay+ payment method to pay, your client side initiates a payment request and opens the Alipay+ checkout page, which displays all the Mobile Payment Providers (MPPs) that are supported by Alipay+ and the promotion information corresponding to each MPP.

• If the terminal type of your client side is Web and the MPP that the user chooses supports code-scanning payment, the user can open the MPP app to scan the QR code for payment.
• Otherwise, the user chooses one of the MPPs to pay.

After the user selects the MPP, the user is redirected to the MPP side. (Step 8-17)

3. After the user completes the payment at the MPP side, Alipay+ notifies your server side of the payment result, which is then synced to your client side. At the same time, your server side can initiate an inquiryPayment request to obtain the payment result asynchoronously. (Step 18-25)
4. Your client side displays the payment result to the user. (Step 26)

Step 1: Render the payment method page

To render the payment method page with the Alipay+ logo and promotion information, your client side needs to take the following steps:

1. Consult the information about the Alipay+ payment method

Your client side needs to consult the following information about the payment method from Alipay+:

• Whether the Alipay+ payment method is available.
• If available, the Alipay+ logo and promotion information (if any) are also returned.

Alipay+ provides two methods for your client side to consult the information about the Alipay+ payment method. The following table shows the details and an applicable scenario that is recommended for each method.

For more information about how to implement these two methods, see How to consult the payment information.

2. Render the payment method page with the information

With the information that is returned in Step1.1, your client side needs to follow the Alipay+ Brand Guidelines to render the payment method page. For more information, see Brand Display Guidelines for Cashier Payment.

Step 2: Initiate a payment

To obtain the information about Alipay+ payment checkout page and create an order in Alipay+, the ACQP needs to take the following steps:

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.

Processing logic

• The following parameters must be 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 : specifies the terminal type and operation system of your client side that the user initiates the request. The following table lists the detailed information about this parameter:

Note: These two parameters do not specify the terminal type and the operation 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.
• paymentMethod.paymentMethodType: specifies the payment method as CONNECT_WALLET.
• paymentFactor.presentmentMode: specifies the presentment mode as UNIFIED.

• 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 resutStatus filed is returned as S.

Sample

The ACQP sends a request to Alipay+.

{
  "userRegion": "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",
    "presentmentMode": "UNIFIED"
  },
  "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": "CONNECT_WALLET"
  }
}

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"
  },
  "normalUrl": "http://iopengw-sea.com/api/open/v1/ac/cashier/self/codevalue/checkout.htm?codeValue=https%3A%2F%2Fqr.alipayplus.com%2F281666040092tUox5AICEzTlESzUJe26IPnn",
  "paymentData": "{\"displayPaymentAmount\":\"100.00\",\"displayPaymentCurrency\":\"USD\",\"wallets\":[{\"enabled\":true,\"promoNames\":[\"{\\\"en_US\\\":\\\"30% off\\\",\\\"th_TH\\\":\\\"คูปองส่วนลด 30 บาท\\\"}\"],\"searchKeywords\":[\"dana wallet\"],\"walletName\":\"DANA\"}]}"
}

More information

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

2. Open the Alipay+ checkout page

After your server side handles the pay API response successfully, your client side needs to further open the Alipay+ checkout page, where the user can choose an MPP that is supported by Alipay+ to pay.

The following two solutions are provided for your client side to open the Alipay+ checkout page:

SDK integration solution for App

If the merchant platform is an app, it is recommended that your client side integrate the SDK provided by the ACQP to smoothly open the Alipay+ checkout page, thus facilitating the user payment.

For more information about how to use an SDK to open the Alipay+ checkout page, see How to open Alipay+ checkout page with SDK.

Non-SDK integration solution

If the merchant does not have an app or does not want to integrate an SDK, your client side can also open the Alipay+ checkout page by using the payment URL that is returned by your server side.

The payment URL is specified for the normalUrl parameter that is returned in Step2.1. Depending on the terminal type and the operation system of your client side, the way to open the payment URL is different.

Refer to the following samples for details.

For Android app:

try {
    Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(normalUrl));
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); 
    startActivity(intent);
} catch (Exception e) {
    e.printStackTrace();
}

For iOS app

if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0) {
    [[UIApplication sharedApplication] openURL:url options:@{} completionHandler:nil];
}else{
    [[UIApplication sharedApplication] openURL:url];
}

For Web or WAP:

window.location.href = normalUrl;

3. Handle the redirection from the MPP

After the user procceds with the payment order to a status of success, failure or unknown (for example, give up the payment order), the MPP can redirect the user to a predetermined page at your side, for example, the merchant payment result page. The URL of the predetemined 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 Step 3.

(Recommeded) Add a confirmation dialogue

To help the user see the payment result even if the redirection from the MPP client to your client fails, it is recommended that you add a confirm dialogue on your merchant page after the user is redirected to the MPP client.

Note: If the MPP client opens the redirect URL successfully, you need to dismiss the confirm dialogue.

The logic of adding the confirm dialogue depends on whether the Alipay+ SDK is integrated with your client:

• Alipay+ SDK is integrated: add logic in the callback of the showPaymentSheet API to add the confirm dialogue after the user is redirected to the MPP client.
• Alipay + SDK is not integrated: add the confirm dialogue after the Alipay+ checkout page is opened.

The following figure shows an example of the confirm dialogue.

Figure 2. Example of a confirm dialogue

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.

The suggestion mentioned above applies to the Web, App, and WAP terminals. Besides, for a website experience, it is also recommended that you open a new tab for the user when the user is redirected to the MPP page from the merchant page. Thus the user can easily switch between tabs if the MPP page fails to be opened; otherwise, the user has to try to use the back button of the page to return to the merchant page, which usually fails.

Step 3: Handle the payment result

Your server side can get the payment result by calling the inquiryPayment API and receiving the notifyPayment API request. For cashier payment, the inquiryPayment and notifyPayment APIs are both required to be integrated.

Alipay+ sends the notifyPayment API request to the ACQP when the user completes the payment. Also, the ACQP can call the inquiryPayment API to get the payment result from Alipay+. When the user completes the payment but the ACQP fails to receive the notifyPayment API request due to some network issues, the inquiryPayment API can take effect to ensure the final payment result is returned.

inquiryPayment

The inquiryPayment API is called to query the final status of the transaction.

Processing logic

• Your server side calls the inquiryPayment API to get the payment result and might receive different results from Alipay+. Follow instructions below to handle the result:

• The maximum result inquiry polling time must be at least 10 minutes longer than the Alipay+'s payment expiration time.
• If the transaction needs to be terminated before getting the final payment result, the cancelPayment API is required to be called to cancel the transaction. For more information about how to cancel a transaction, see Cancel the transaction.

Sample

The ACQP sends request to Alipay+.

{
 "paymentRequestId":"pay_1089760038715669_10277574507566920200101234567897890"
}

Alipay+ returns response to the ACQP.

{
  "acquirerId": "1111088000000000002",
  "pspId": "1022172000000000001",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentRequestId":"pay_1089760038715669_102775745075669",
  "paymentId": "20200101234567890134567",
  "paymentTime": "2020-01-01T12:01:01+08:30",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "customerId": "1235678",
  "walletBrandName":"KAKAOPAY",
  "transactions":[
                    {
                      "transactionResult":{
                         "resultCode":"SUCCESS",
                         "resultStatus":"S",
                         "resultMessage":"success"
                      },
                      "transactionId":"1111111111111111111",
                      "transactionType":"REFUND",
                      "transactionStatus":"SUCCESS",
                        "transactionRequestId":"pay_1089760038715669_102775745075670",
                      "transactionAmount":{
                          "value":"500",
                          "currency":"USD"
                      },
                      "transactionTime":"2019-06-01T12:01:01+08:30"
                     }
   ],
  "settlementAmount": {
    "value": "9000",
    "currency": "USD"
  },
  "settlementQuote": {
    "quoteCurrencyPair": "JPY/USD",
    "quoteExpiryTime": "2021-06-02T13:15:48+08:00",
    "quoteId": "046793306919858814",
    "quotePrice": "0.9",
    "quoteStartTime": "2021-05-30T13:15:48+08:00"
  }

}

More information

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

notifyPayment

Alipay+ calls the notifyPayment interface to notify the ACQP about the payment result when the payment reaches a final state of success or failure. After that, the ACQP needs to notify the merchant of the result accordingly.

Processing logic

Accept notifications

For a successful payment transaction, an HTTP POST is fired once the transaction is successfully completed. The HTTP request is sent in the raw JSON, of which the Content-Type request header is specified as application/json. Ensure that your server side can access the HTTP body accordingly.

For more information about what the request header, the successful payment notification request body, and the failed payment notification body look like, see the samples below.

Verify the signature

The notification request that Alipay+ sends to the ACQP is signed. The ACQP needs to verify the signature to confirm whether the notification is sent from Alipay+. For how to validate a signature, see Validate a signature.

After the notification is delivered successfully, verify whether the values of the paymentAmount and paymentRequestId parameters are as you expect (for example, the amount that you have calculated for the order that you are going to ship).

Acknowledge the notification with the required response

After receiving the notification, no matter whether the order processing succeeds or fails, your server side must return a receipt acknowledgment message to Alipay+. Meanwhile, the required response must also be signed.

For more information about what the header and body of the response look like, see the samples below.

Note: The notifyPayment interface cannot accept the failure that is caused by business reasons, for example, risk control validation failure. If the payment fails due to some business reasons, the ACQP must firstly accept the payment notification and return SUCCESS to Alipay+, and then call the cancelPayment interface to perform refunds.

Retrial mechanism

After receiving the notification, your server side must respond with an HTTP status code of 200 and send an acknowledgement with result.resultStatus of S to indicate that your server side received and processed the call. If your server side responds with other status code, or acknowledge with other values, Alipay+ takes the notification delivery as unsuccessful. Therefore, Alipay+ will retry the notification sending.

• The interval between two adjacent times is: 2m, 10m, 10m, 1h, 2h, 6h, 15h
• 7 times - up to 24 hours 22 minutes

Sample

Alipay+ sends a request to the ACQP.

{
 "acquirerId": "1111088000000000002",
 "pspId":"1022172000000000001",
 "paymentResult": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 },
 "paymentRequestId":"pay_1089760038715669_102775745075669", 
 "paymentId":"20200101234567890134567", 
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "customerId":"1235678",
 "walletBrandName":"KAKAOPAY"
}

The ACQP returns a response to Alipay+.

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 }
}

More information

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

Collaboration between inquiryPayment and notifyPayment

The following figure illustrates how the inquiryPayment and notifyPayment APIs collaborate to ensure you get the payment result.

Figure 3. Collaboration between inquiryPayment and notifyPayment

Before reading the information below, ensure that at least a table that includes orderNo and status is created in your database.

• It is recommended that you can confirm whether the order status is init in the table before you send the inquiryPayment API request. You don't need to call the inquiryPayment API when you have got the final payment result via the notifyPayment API.
• If the value of the paymentResult parameter in the response of the inquiryPayment API is SUCCESSor FAIL , your server side needs to update the order status in the table. Otherwise, your server side needs to retry the inquiryPayment API request to get the final payment result.
• Your server side needs to return the response when receiving the notifyPayment API request from Alipay+, and then confirm whether the order status is init in the table before you update the order status. You don't need to update the order status when you have got the final payment result via the inquiryPayment API.