目录

paymentService (HarmonyOS Payment Service)

This module provides payment and contract signing service capabilities, including basic payment, payment and contract signing, combined payment, and entrusted payment.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).

System capability: SystemCapability.Payment.PaymentService

Since: 4.1.0(11)

Modules to Import

import { paymentService } from '@kit.PaymentKit';

PayResult

Defines the payment information after a user selects a payment method and confirms the payment in the general checkout.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.Payment.PaymentService

Since: 5.0.2(14)

Name Type Read-Only Optional Description
selectedPaymentType string No Yes

Payment method selected by a user.

URL-based redirection to the third-party payment page:

wechat_pay: WeChat Pay.

ali_pay: Alipay.

- Other values (indicating the configurations applied when the merchant applies for the third-party payment method)

API-based redirection to the third-party payment page:

- wechat_pay_sdk: WeChat Pay

- ali_pay_sdk: Alipay

- Other values (indicating the configurations applied when the merchant applies for the third-party payment method)
clientToken string No Yes Client token. It is used to verify the information about the caller.
nextStep string No Yes Next payment step.
extraInfo string No Yes Reserved field. The value is a JSON string. Example: {"selectPayType":"wechat_pay"}.
payload string No Yes

Reserved information. If this input parameter is passed when the API is requested, it will be returned as-is in the API response.

Note: In the HTML5 payment scenario, the value must be "AP".

PaymentInfo

Defines the payment order information passed when the third-party payment starts the general checkout.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.Payment.PaymentService

Since: 5.0.2(14)

Name Type Read-Only Optional Description
tradeSummary string No Yes Order summary. If this parameter is not set, it is left empty by default.
amount number No Yes Total order amount, in cents. The value must be an integer greater than 0. If a value beyond the value range is passed, the request will be abnormal.
currency string No Yes

Currency unit. If this parameter is not set, it is left empty by default.

NOTE

- If this parameter is not passed, the checkout screen does not display the currency unit.

- If this parameter is passed, the checkout screen converts it to a value with the currency symbol (such as ¥) if possible; otherwise, the checkout screen displays the original value.
extraInfo string No Yes

Reserved field. The value is a JSON string. If this parameter is not set, it is left empty by default.

Note: Merchants can use the reserved field to specify the payment method. For example, you can specify the payment method by passing {"selectPayType":"wechat_pay|xxx"}.

PickerResult

Defines the order payment information returned to the developer when the third-party payment starts the general checkout.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.Payment.PaymentService

Since: 5.0.2(14)

Name Type Read-Only Optional Description
selectedPaymentType string No Yes

Payment method selected by a user.

URL-based redirection to the third-party payment page:

wechat_pay: WeChat Pay.

ali_pay: Alipay.

- Other values (indicating the configurations applied when the merchant applies for the third-party payment method)

API-based redirection to the third-party payment page:

- wechat_pay_sdk: WeChat Pay

- ali_pay_sdk: Alipay

- Other values (indicating the configurations applied when the merchant applies for the third-party payment method)
clientToken string No Yes Client token. It is used to verify the information about the caller.

BindCardResult

Defines the card binding result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.5(17).

System capability: SystemCapability.Payment.PaymentService

Since: 5.0.5(17)

Name Type Read-Only Optional Description
hasBankCard boolean No No

Whether the user has a bank card bound.

- true: yes

- false: no
hasJustBoundCard boolean No Yes

Whether the user has completed card binding after opening the card management page.

- true: yes

- false: no

requestPayment

requestPayment(context: common.UIAbilityContext, orderStr: string): Promise<void>

Provides features such as basic payment and payment with contract signing. Before calling this method, ensure that the network is connected. After this method is called, the Payment Kit checkout screen is displayed. This method uses a promise to return the payment result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).

System capability: SystemCapability.Payment.PaymentService

Since: 4.1.0(11)

Parameters

Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context. If this parameter is not passed, error code 401 will be reported.
orderStr string Yes Order information passed when the checkout screen is started. orderStr is a JSON string. If this parameter is not passed, error code 401 will be reported. Example: {"app_id":"","merc_no":"","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}.

Returns

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1001930000 The operation was canceled by the user.
1001930001 Pay failed.
1001930002 The transaction has been processed.
1001930010 Duplicate request.
1001930011 Network connection error.

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

import { paymentService } from '@kit.PaymentKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  requestPaymentPromise() {
    // Please use the actual order information (orderStr).
    const orderStr = '{"app_id":"***","merc_no":"***","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}';
    paymentService.requestPayment(this.context, orderStr)
      .then(() => {
        // The payment is successful.
        console.info('succeeded in paying');
      });
  }

  build() {
    Column() {
      Button('requestPaymentPromise')
        .type(ButtonType.Capsule)
        .width('50%')
        .margin(20)
        .onClick(() => {
          this.requestPaymentPromise();
        })
    }
    .width('100%')
    .height('100%')
  }
}

requestPayment

requestPayment(context: common.UIAbilityContext, orderStr: string, callback: AsyncCallback<void>): void

Provides features such as basic payment and payment with contract signing. Before calling this method, ensure that the network is connected. After this method is called, the Payment Kit checkout screen is displayed. This method uses a callback to return the payment result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 4.1.0(11).

System capability: SystemCapability.Payment.PaymentService

Since: 4.1.0(11)

Parameters

Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context. If this parameter is not passed, error code 401 will be reported.
orderStr string Yes Order information passed when the checkout screen is started. orderStr is a JSON string. If this parameter is not passed, error code 401 will be reported. Example: {"app_id":"","merc_no":"","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}.
callback AsyncCallback<void> Yes Callback used to return the result. If the payment is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1001930000 The operation was canceled by the user.
1001930001 Pay failed.
1001930002 The transaction has been processed.
1001930010 Duplicate request.
1001930011 Network connection error.

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

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;
  requestPaymentCallBack() {
    // Please use the actual order information (orderStr).
    const orderStr = '{"app_id":"***","merc_no":"***","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}';
    paymentService.requestPayment(this.context, orderStr, (error: BusinessError) => {
      if (error) {
        // The payment fails.
        console.error(`failed to pay, error.code: ${error.code}, error.message: ${error.message}`);
        return;
      }
      // The payment is successful.
      console.info('succeeded in paying');
    });
  }

  build() {
    Column() {
      Button('requestPaymentCallBack')
        .type(ButtonType.Capsule)
        .width('50%')
        .margin(20)
        .onClick(() => {
          this.requestPaymentCallBack();
        })
      }
    .width('100%')
    .height('100%')
  }
}

requestContract

requestContract(context: common.UIAbilityContext, contractStr: string): Promise<void>

Provides the contract signing feature. Before calling this method, ensure that the network is connected. After this method is called, the Payment Kit checkout screen for contract signing is displayed. This method uses a promise to return the contract signing result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.PaymentService

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context. If this parameter is not passed, error code 401 will be reported.
contractStr string Yes Input parameter for starting the checkout screen for contract signing. contractStr is a JSON string. If this parameter is not passed, error code 401 will be reported.

Returns

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1001930000 The operation was canceled by the user.
1001930002 The transaction has been processed.
1001930003 Withhold failed.
1001930010 Duplicate request.
1001930011 Network connection error.

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

import { paymentService } from '@kit.PaymentKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  requestContractPromise() {
    // Please use the actual input parameter information (**contractStr**).
    const contractStr = '{"appId":"***","preSignNo":"***"}';
    paymentService.requestContract(this.context, contractStr)
      .then(() => {
        // The contract signing is successful.
        console.info('succeeded in signing');
      });
  }

  build() {
    Column() {
      Button('requestContractPromise')
        .type(ButtonType.Capsule)
        .width('50%')
        .margin(20)
        .onClick(() => {
          this.requestContractPromise();
        })
    }
    .width('100%')
    .height('100%')
  }
}

requestContract

requestContract(context: common.UIAbilityContext, contractStr: string, callback: AsyncCallback<void>): void

Provides the contract signing feature. Before calling this method, ensure that the network is connected. After this method is called, the Payment Kit checkout screen for contract signing is displayed. This method uses a callback to return the contract signing result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.PaymentService

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context. If this parameter is not passed, error code 401 will be reported.
contractStr string Yes Input parameter for starting the checkout screen for contract signing. contractStr is a JSON string. If this parameter is not passed, error code 401 will be reported.
callback AsyncCallback<void> Yes Callback used to return the result. If the contract signing is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1001930000 The operation was canceled by the user.
1001930002 The transaction has been processed.
1001930003 Withhold failed.
1001930010 Duplicate request.
1001930011 Network connection error.

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

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;
  requestContractCallBack() {
    // Please use the actual callback function (contractStr).
    const contractStr = '{"appId":"***","preSignNo":"***"}';
    paymentService.requestContract(this.context, contractStr, (error: BusinessError) => {
      if (error) {
        // The contract signing fails.
        console.error(`failed to sign, error.code: ${error.code}, error.message: ${error.message}`);
        return;
      }
      // The contract signing is successful.
      console.info('succeeded in signing');
    });
  }

  build() {
    Column() {
      Button('requestContractCallBack')
        .type(ButtonType.Capsule)
        .width('50%')
        .margin(20)
        .onClick(() => {
          this.requestContractCallBack();
        })
      }
    .width('100%')
    .height('100%')
  }
}

requestPayment

requestPayment(context: common.UIAbilityContext, orderStr: string, payload: string): Promise<PayResult>

Provides the features of displaying the checkout screen and redirecting to a third-party payment screen. Before calling this method, ensure that the network is connected. After the user selects a payment method and confirms the payment on the checkout screen, this method uses a promise to return the payment result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.Payment.PaymentService

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.2(14)

Parameters

Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context. If this parameter is not passed, error code 401 will be reported.
orderStr string Yes

Order information passed to the checkout screen or third-party payment page.

The value of orderStr is a JSON string. If this parameter is not passed, error code 401 will be reported. Example: {"app_id":"","merc_no":"","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}.
payload string Yes

Reserved information. If this input parameter is passed when the API is requested, it will be returned as-is in the API response.

Note: To start the Huawei Pay checkout screen, this parameter must be left empty or set to an empty string. In the HTML5 payment scenario, the value must be "AP" when redirecting to a third-party payment page.

Returns

Type Description
Promise<PayResult>

Promise used to return the PayResult.

Note: In the Huawei Pay scenario, PayResult may be empty. The payment result is subject to the callback notification or query result.

Error codes

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1001930000 The operation was canceled by the user.
1001930001 Pay failed.
1001930002 The transaction has been processed.
1001930010 Duplicate request.
1001930011 Network connection error.

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

import { paymentService } from '@kit.PaymentKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  requestPaymentPromise() {
    // Please use the actual order information (orderStr) to pay for the order.
    // For details about the order information example, please refer to '{"app_id":"***","merc_no":"***","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}'.
    // Please use the actual order information (orderStr) to redirect to the third-party payment page.
    const orderStr = '{"nextAction":"L","linkUrl":"","scheme":"","clientToken":"***"}';
    paymentService.requestPayment(this.context, orderStr, 'AP')
      .then((payResult: paymentService.PayResult) => {
        // The payment is successful.
        console.info('succeeded in paying, pay result: ', payResult);
      });
  }

  build() {
    Column() {
      Button('requestPaymentPromise')
        .type(ButtonType.Capsule)
        .width('50%')
        .margin(20)
        .onClick(() => {
          this.requestPaymentPromise();
        })
    }
    .width('100%')
    .height('100%')
  }
}

cashierPicker

cashierPicker(context: common.UIAbilityContext, paymentInfo: PaymentInfo): Promise<PickerResult>

Provides the feature of displaying the checkout screen. Before calling this method, ensure that the network is connected. After the user selects a payment method and confirms the payment on the checkout screen, this method uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).

System capability: SystemCapability.Payment.PaymentService

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.2(14)

Parameters

Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context. If this parameter is not passed, error code 401 will be reported.
paymentInfo PaymentInfo Yes Payment information passed when the general checkout is started.

Returns

Type Description
Promise<PickerResult> Promise used to return the PickerResult.

Error codes

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1001930000 The operation was canceled by the user.
1001930001 Pay failed.
1001930002 The transaction has been processed.
1001930010 Duplicate request.
1001930011 Network connection error.

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

import { paymentService } from '@kit.PaymentKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  requestCashierPicker() {
    // Please use the actual payment 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);
      });
  }

  build() {
    Column() {
      Button('requestCashierPicker')
        .type(ButtonType.Capsule)
        .width('50%')
        .margin(20)
        .onClick(() => {
          this.requestCashierPicker();
        })
    }
    .width('100%')
    .height('100%')
  }
}

requestBindCard

requestBindCard(context: common.UIAbilityContext | common.UIExtensionContext): Promise<BindCardResult>

Provides the card binding feature. After this method is called, the Payment Kit card binding screen is displayed. This method uses a promise to return the card binding result. Before calling this method, ensure that the network is connected.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.5(17).

System capability: SystemCapability.Payment.PaymentService

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.5(17)

Parameters

Parameter Type Mandatory Description
context common.UIAbilityContext | common.UIExtensionContext Yes UIAbility context. If this parameter is not passed, error code 401 will be reported.

Returns

Type Description
Promise<BindCardResult> Promise used to return the BindCardResult.

Error codes

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error.Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1001930000 The operation was canceled by the user.
1001930011 Network connection error.

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

import { paymentService } from '@kit.PaymentKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  requestBindCardPromise() {
    paymentService.requestBindCard(this.context)
      .then((bindCardResult: paymentService.BindCardResult) => {
        // The card is successfully bound.
        console.info(`succeeded in binding card. result: ${bindCardResult}`);
      });
  }

  build() {
    Column() {
      Button('requestBindCardPromise')
        .type(ButtonType.Capsule)
        .width('50%')
        .margin(20)
        .onClick(() => {
          this.requestBindCardPromise();
        })
    }
    .width('100%')
    .height('100%')
  }
}