Alipay+ DocsAlipay+ Docs
APIs & SDKs

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 a 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 on 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.

商户调用机构服务端下单.jpg

Figure 1. Call ACQP server to place an order

The workflow contains the following steps:

  1. 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).
    1. 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).
    2. If some other payment method is selected, the ACQP server places an order with the selected payment method following the existing agreement (Step 7).
  1. The ACQP server returns the processing result of order placement to the merchant app (Step 8-9).
  2. 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 on 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.

商户调用机构SDK下单.jpg

Figure 2. Call ACQP SDK to place an order

The workflow contains the following steps:

  1. 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)
  2. The ACQP SDK sends the order information to the ACQP server (Step 6), which checks the selected payment method.
    1. 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)
    2. If some other payment method is selected, the ACQP server places an order with the selected payment method following the existing agreement (Step 10).
  1. 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 on 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 quick start.

For more information about how to integrate the iOS SDK provided by Alipay+, see iOS SDK quick start.

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

copy
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

copy

[[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 currently provide 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:

copy
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:

copy
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 in Step 2.3: Handle the redirection from the MPP of the Accept payments topic to handle the redirection from the MPP.

Learn more about

Home
Get Support
Need more help?