How to open Alipay+ checkout page with SDK
This chapter introduces how to open the Alipay+ checkout page by using an SDK.
This solution is applicable when the merchant platform is an app and provides better end-user experience as a prebuilt Alipay+ checkout page (also known as the payment sheet) is provided by Alipay+. This prebuilt page gets rendered faster than opening the payment URL in the non-SDK integration solution. Therefore, it is recommended that you open the Alipay+ checkout page by using an SDK.
Note: If only one Alipay+ payment method is available, the Alipay+ checkout page is not displayed. In this case, the user is directly redirected to the payment confirmation page at the MPP side.
Integration modes
The SDK integration mode differs depending on how the merchant places orders to you. Generally speaking, your merchant may call your server or call your SDK to place orders.
Mode 1: Merchant calls ACQP server to place orders
The following figures illustrate the main workflow of opening the Alipay+ checkout page when the merchant calls your server to place orders.
Figure 1. Call ACQP server to place order
The workflow contains the following steps:
- A user selects a payment method to initiate a payment. The merchant server prepares the order information and calls the ACQP server to place an order to the ACQP, which checks the selected payment method (Step 1-3).
- If the Alipay+ payment method is selected, the ACQP server calls the pay API to place an order to Alipay+. Alipay+ generates the paymentData parameter based on the order information and returns it to the ACQP server (Step 4-6).
- If some other payment method is selected, the ACQP server places an order with the selected payment method following the existing agreement (Step 7).
- The ACQP server returns the processing result of order placement to the merchant app (Step 8-9).
- The merchant app calls the ACQP SDK to render the payment page (Step 10). The ACQP SDK also checks the selected payment method.
- If the Alipay+ payment method is selected, the ACQP SDK extracts the paymentData parameter and calls the showPaymentSheet API provided by the Alipay+ SDK. The Alipay+ SDK then renders the Alipay+ checkout page, which displays a list of MPPs that are supported by Alipay+ and relevant promotion information (Step 11-13). The user can choose an MPP and will be redirected by the Alipay+ SDK to complete the payment.
Note:
- If the paymentData parameter contains information about only one payment method, the Alipay+ SDK does not render the Alipay+ checkout page and directly redirects the user to the MPP side.
- If the Alipay payment method is selected, the Alipay+ SDK notifies the ACQP SDK of the payment result in the callback event of the showPaymentSheet API. However, the event notification returned by the Alipay+ SDK only signals the termination of payment processing at the Alipay side. To obtain the final payment result from Alipay+, you need to integrate the inquiryPayment and notifyPayment APIs. For more information, see Handle the payment result.
- If some other payment method is selected, the ACQP SDK follows the existing payment flow to process the order accordingly (Step 14).
Mode 2: Merchant calls ACQP SDK to place orders
The following figures illustrate the main workflow of opening the Alipay+ checkout page when the merchant calls your own SDK to place orders.
Figure 2. Call ACQP SDK to place order
The workflow contains the following steps:
- A user selects a payment method to initiate a payment. The merchant app prepares the order information and calls the ACQP SDK to place an order to the ACQP. (Step 1-5)
- The ACQP SDK sends the order information to the ACQP server (Step 6), which checks the selected payment method.
- If the Alipay+ payment method is selected, the ACQP server calls the pay API to place an order to Alipay+. Alipay+ generates the paymentData parameter based on the order information and returns it to the ACQP server. (Step 7-9)
- If some other payment method is selected, the ACQP server places an order with the selected payment method following the existing agreement (Step 10).
- The ACQP server returns the processing result of order placement to the ACQP SDK (Step 11), which also checks the selected payment method.
- If the Alipay+ payment method is selected, the ACQP SDK extracts the paymentData parameter and calls the showPaymentSheet API provided by the Alipay+ SDK. The Alipay+ SDK then renders the Alipay+ checkout page, which displays a list of MPPs that are supported by Alipay+ and relevant promotion information (Step 12-14). The user can choose an MPP and will be redirected by the Alipay+ SDK to complete the payment.
Note:
- If the paymentData parameter contains information about only one payment method, the Alipay+ SDK does not render the Alipay+ checkout page and directly redirects the user to the MPP side.
- If the Alipay payment method is selected, the Alipay+ SDK notifies the ACQP SDK of the payment result in the callback event of the showPaymentSheet API. However, the event notification returned by the Alipay+ SDK only signals the termination of payment processing at the Alipay side. To obtain the final payment result from Alipay+, you need to integrate the inquiryPayment and notifyPayment APIs. For more information, see Handle the payment result.
- If some other payment method is selected, the ACQP SDK follows the existing payment flow to process the order accordingly. (Step 15)
Integration methods
Depending on whether you have your own SDK, Alipay+ provides different methods for you to implement the function of opening the Alipay+ checkout page.
If you have your own SDK, you can integrate your own SDK with the Alipay+ ACQP Client SDK (Alipay+ SDK for short) and then provide the SDK to the merchant.
If you have no SDK, you can create a new SDK to wrap up the Alipay+ SDK and then provide the SDK to the merchant.
It is recommended that you integrate Alipay+ and also other payment methods into the SDK that is provided to the merchant. This effectively saves the integration costs for the merchant as this allows the merchant to integrate only one SDK to use all payment options that you have to offer.
The following section introduces the actions that you need to take with the different integration methods.
Method 1: If ACQP has its own SDK
If you have your own SDK, the following actions are required regardless of whether the merchant calls your server or your own SDK to place orders:
1. Integrate the Alipay+ SDK
Before you provide your own SDK to the merchant, you need to integrate your own SDK with the Alipay+ SDK.
For more information about how to integrate the Android SDK provided by Alipay+, see Android SDK Quickstart.
For more information about how to integrate the iOS SDK provided by Alipay+, see iOS SDK Quickstart.
2. Present the Alipay+ checkout page
After your SDK receives the order placement data, the SDK needs to check whether the Alipay+ payment method is selected. If so, the SDK needs to call the showPaymentSheet API to present the prebuilt Alipay+ checkout page provided by the Alipay+ SDK to the user.
Processing logic
When sending the showPaymentSheet API request, you need to configure two input parameters.
The first parameter is used to pass in the payment data returned by your server. The second parameter is used to pass in custom callbacks for handling events that occur during the lifecycle of the payment sheet.
Samples
for Android
String paymentData = "XXX";
AlipayPlusClient.showPaymentSheet(paymentData, new IAPPaymentSheetEventCallback<IAPPaymentSheetEvent>() {
public void onSheetEvent(IAPPaymentSheetEvent event) {
switch(event.name) {
case "EVENT_SELECT_AND_PAY":
//your own logic; required
break;
case "EVENT_THROW_EXCEPTION":
//your own logic. optional
break;
case "EVENT_USER_CANCEL":
//your own logic; optional
break;
case "EVENT_SHOW_SUCCESS":
//your own logic; optional
break;
}
}
})
for iOS
[[AlipayPlusClient shared] showPaymentSheetWithData:@"xxx"
callback:^(IAPPaymentSheetEvent *sheetEvent) {
if ([sheetEvent.name isEqualToString:IAPPaymentSheetEventDidSelectWalletAndPay]) {
//your own logic; required
} else if ([sheetEvent.name isEqualToString:IAPPaymentSheetEventThrowException]) {
//your own logic. optional
} else if ([sheetEvent.name isEqualToString:IAPPaymentSheetEventUserDidCancel]) {
//your own logic; optional
} else if ([sheetEvent.name isEqualToString:IAPPaymentSheetEventDidShow]) {
//your own logic; optional
}
}];
Method 2: If ACQP has no SDK
If you previously provides no SDK to the merchant, you need to create a new SDK to wrap up the Alipay+ SDK. To do this, different actions are required depending on whether the merchant calls your new SDK or your server to place orders.
Merchant calls ACQP SDK to place orders
The following actions are required to implement the integration mode where the merchant calls your new SDK to place orders.
1. Provide instructions on how to construct order information
With the new ACQP SDK, the merchant no longer calls your server API to place orders. Instead, the merchant uses an ACQP SDK API to do this.
To ensure data security, the merchant app needs to send order information to the merchant server, which uses a private key to generate a signature and adds the signature to the order information. After receiving the signed order information from the merchant server, the merchant app then calls the ACQP SDK API to place orders.
2. Create a new ACQP SDK
You need to create a new SDK to wrap up the Alipay+ SDK. To do this, refer to the following sample code for Android:
public class PaymentSheet {
private static final String REQUEST_URL = "your serevr url";
/*
* Used by merchant to open payment sheet; paymentData represents signed order information
* constructed following your instructions
*/
public void showPaymentSheet(String orderInfo, Callback callback) {
new Thread(() -> {
Response response = placeOrder(orderInfo);
if (response.code() != HttpURLConnection.HTTP_OK) {
// your own logic, for example, notify merchant of the failure
return;
}
String resBody = new String(response.body(), "UTF-8");
JSONObject resJson = new JSONObject(resBody);
if ("CONNECT_WALLET".equals(resJson.getString("paymentMethod"))) {
initAliplusSdk(resJson.getString(merchantId));
AlipayPlusClient.showPaymentSheet(resJson.getString("paymentData"), new IAPPaymentSheetEventCallback() {
@override
public void onSheetEvent(IAPPaymentSheetEvent event) {
// your own logic
}
});
} else {
// Optional. If you support only the Alipay+ payment method, make an agreement with merchant that
// this function is called only when the Alipay+ payment method is selected.
// Alternatively, use other payment method to process order info
}
}).start();
}
/**
* Place order to your server
*/
private Response placeOrder(String orderInfo) {
Request.Builder requestBuilder = new Request.Builder().url(REQUEST_URL);
FormBody.Builder formBuilder = new FormBody.Builder();
formBuilder.add("orderInfo", orderInfo);
RequestBody formBody = formBuilder.build();
requestBuilder.post(formBody);
Response response = new OkHttpClient()
.newCall(requestBuilder.build())
.execute();
return response;
}
/**
* init Alipay+ sdk
*/
private void initAliplusSdk(String merchantId){
IAPConfiguration configuration = new IAPConfiguration();
configuration.envType = "SANDBOX";
configuration.acquirerId = "your acquire id";
configuraiton.merchantId = merchantId;
AlipayPlusClient.setConfiguration(configuration);
}
}
Take the following things into consideration when you create the SDK:
- The showPaymentSheet API is used by the merchant app to open the payment sheet. The orderInfo parameter represents the signed order information that is passed in by the merchant server.
- The placeOrder API is used by your SDK to place orders to your server and obtain the processing result of order placement.
- After obtaining the processing result of order placement, your SDK needs to check whether the Alipay+ payment method is selected. If so, your SDK needs to call the showPaymentSheet API to open the payment sheet provided by Alipay+.
- You can choose to support only the Alipay+ payment method in the showPaymentSheet API. In this case, you need to make an agreement with your merchant that the showPaymentSheet API is called only when the Alipay+ payment method is selected.
- It is recommended that you integrate all payment methods into the SDK that is provided to the merchant. This effectively saves the integration costs for the merchant.
Merchant calls ACQP server to place orders
The following actions are required to implement the integration mode where the merchant calls your server to place orders.
1. Provide an API for placing orders to your server
You need to provide the merchant with an API for placing orders to your server. This API needs to take order information as input and return the paymentData parameter if the Alipay+ payment method is selected.
2. Provide an API for opening the payment sheet
You need to provide the merchant with an API for opening the payment sheet. To do this, you can refer to the following sample code:
public class PaymentSheet {
/**
* Used by merchant to open payment sheet; paymentData represents signed order information constructed following your instructions
*/
public void showPaymentSheet(JSONObject orderInfoJson, Callback callback) {
if ("CONNECT_WALLET".equals(orderInfoJson.getString("paymentMethod"))) {
initAliplusSdk(orderInfoJson.getString("merchantId"));
AlipayPlusClient.showPaymentSheet(resJson.getString("paymentData"), new IAPPaymentSheetEventCallback() {
@override
public void onSheetEvent(IAPPaymentSheetEvent event) {
// your own logic
}
});
} else {
// Optional. If you support only the Alipay+ payment method
//make an agreement with merchant that this function is called only
// when the Alipay+ payment method is selected.
//Alternatively, use other payment method to process order info
}
}
private void initAliplusSdk(String merchantId){
IAPConfiguration configuration = new IAPConfiguration();
configuration.envType = "SANDBOX";
configuration.acquirerId = "your acquire id";
configuraiton.merchantId = merchantId;
AlipayPlusClient.setConfiguration(configuration);
}
}
Take the following things into consideration when you create the API:
- The showPaymentSheet API is used by the merchant app to open the payment sheet. The orderInfo parameter represents the order information that is passed in by your server.
- After obtaining the order placement data, your SDK needs to check whether the Alipay+ payment method is selected. If so, your SDK needs to call the showPaymentSheet API to open the payment sheet provided by Alipay+.
- You can choose to support only the Alipay+ payment method in the showPaymentSheet API. In this case, you need to make an agreement with your merchant that the showPaymentSheet API is called only when the Alipay+ payment method is selected.
- It is recommended that you integrate all payment methods into the SDK that is provided to the merchant. This effectively saves the integration costs for the merchant.
Next Steps
Follow the instructions provided in Step 2.3: Handle the redirection from the MPP of the Accept payments topic to handle the redirection from the MPP.