Use Cases
Since version 5.0.2(14), unified checkout supports external payment.
After a user selects a product in your app/atomic service and places an order, the app/atomic service launches the unified checkout screen, on which the user can only select a third-party payment mode to complete the order payment.
Supported merchant model: Huawei Pay merchant registration is not involved.
The following figure shows the unified checkout screen for external payment.
Integration Process
The table below describes how to implement external payment via unified checkout.
| Step | Description |
|---|---|
| (Optional) Merchant registration | (Optional) Register a third-party payment merchant. The third-party payment will be completed directly on the third-party payment platform. Therefore, you may need to register or create a merchant on this platform. (You are advised to use a new merchant account for distinguishing from existing ones.) |
| Enable the product and configure the payment modes | Request to enable third-party payment and configure related payment modes. |
| Integrate unified checkout | Integrate unified checkout according to the development procedure for external payment. |
Service Process
In the external payment mode, the checkout supports only third-party platform payment, and users cannot use Huawei Pay. The integration process is as follows.
-
The merchant app constructs the PaymentInfo parameter based on the payment modes enabled by the merchant, and calls the cashierPicker API to launch the unified checkout screen of Payment Kit.
-
The unified checkout screen of Payment Kit displays available third-party payment methods. The user selects a third-party payment method and confirms the payment.
-
After the user selects a payment method and confirms the payment on the unified checkout screen, the Payment Kit client returns the payment information PickerResult to the merchant client.
Launching the checkout screen based on URL redirection:
-
The merchant client notifies the merchant server of the payment method.
-
The merchant server calls the third-party payment API to obtain the payment information.
-
The third-party payment server returns the payment redirection URL to the merchant server.
-
The merchant server returns the payment redirection URL to the merchant client.
-
The merchant client constructs the order payment redirection information orderStr and calls the requestPayment API of Payment Kit to redirect the user to the third-party payment screen.
-
The Payment Kit client launches the third-party checkout screen based on the passed payment information.
-
The third-party payment client displays the checkout screen.
-
The user completes the payment.
-
The third-party payment server processes the payment.
-
The third-party payment server synchronously returns the payment status to the third-party payment client. The third-party payment client displays the payment status and goes back to the merchant client.
-
The third-party payment server returns the payment result to the merchant server through the callback API.
-
After receiving the payment result callback request, the merchant server performs signature verification on the payment result based on the requirements of the third-party payment service.
Launching the checkout screen based on the API:
-
The merchant client sends the returned payment method to the merchant server.
-
The merchant server obtains the parameters for launching the third-party checkout screen, and constructs and returns payInfo (the parameters for launching the checkout screen vary with the third-party payment method).
-
The merchant server returns the third-party payment information payInfo to the merchant client.
-
The merchant client uses payInfo to call the ThirdPayClient.pay API of Payment Kit to start the third-party payment client. (The ThirdPayClient.handlePayCallback API can also be called to obtain the third-party payment processing result.)
-
Payment Kit launches the third-party checkout screen.
-
The third-party payment client displays the checkout screen.
-
The user completes the payment.
-
The third-party payment server processes the payment.
-
The third-party payment server synchronously returns the payment status to the third-party payment client. The third-party payment client displays the payment status and goes back to the merchant client.
-
The third-party payment client synchronizes the payment completion result to the Payment Kit client.
-
The Payment Kit client returns the payment result to the merchant client through the ThirdPayClient.handlePayCallback API.
-
The third-party payment server returns the payment result to the merchant server through the callback API.
-
After receiving the payment result callback request, the merchant server performs signature verification on the payment result based on the requirements of the third-party payment service, and returns the payment result to the client.
API Description
The API for launching unified checkout returns the result through a promise. For details about the API, please refer to API Reference.
| API Name | Description |
|---|---|
| cashierPicker(context: common.UIAbilityContext, paymentInfo: PaymentInfo): Promise<PickerResult> | Launches unified checkout of Payment Kit (excluding Huawei Pay). |
| requestPayment(context: common.UIAbilityContext, orderStr: string, payload: string): Promise<PayResult> | Redirects to the third-party checkout screen. |
| pay(payInfo: string): Promise<void>; | Launches the third-party checkout screen. |
| handlePayCallback(want: Want): boolean; | Synchronizes the third-party payment result to the Huawei Pay checkout screen through a callback. |
[h2]Launching the Unified Checkout Screen (On-Device Development)
The merchant client constructs the PaymentInfo parameter and calls the cashierPicker API to launch unified checkout of Payment Kit. After the user selects a payment method and confirms the payment, the Payment Kit client returns the payment information PickerResult to the merchant client.
If the API returns a response using the .then() method, the API request is properly responded. If the API returns a response using the .catch() method, the API request is not properly responded. If the request is abnormal, you can obtain the error code through error.code. For details about the error code, please refer to Error Codes. The sample code is as follows:
import { BusinessError } from '@kit.BasicServicesKit';
import { paymentService } from '@kit.PaymentKit';
import { common } from '@kit.AbilityKit';
@Entry
@Component
struct Index {
context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
requestCashierPickerCallBack() {
// Use your own payment order information (paymentInfo).
const paymentInfo: paymentService.PaymentInfo= {
tradeSummary: "*** transaction",
amount: 100,
currency: 'CNY',
extraInfo: '{"***":"***"}'
}
paymentService.cashierPicker(this.context, paymentInfo)
.then((pickerResult: paymentService.PickerResult) => {
// The payment is successful.
console.info('succeeded in paying, picker result: ', pickerResult);
})
.catch((error: BusinessError) => {
// The payment fails.
console.error(`failed to pay, error.code: ${error.code}, error.message: ${error.message}`);
});
}
build() {
Column() {
Button('requestCashierPickerCallBack')
.type(ButtonType.Capsule)
.width('50%')
.margin(20)
.onClick(() => {
this.requestCashierPickerCallBack();
})
}
.width('100%')
.height('100%')
}
} [h2]Launching the Third-Party Checkout Screen (On-Device Development)
Launch the third-party checkout screen based on the payment method configured in Product Enabling and Configuration.