# paymentService (鸿蒙支付服务)

本模块提供支付、签约服务能力，包括基础支付、支付并签约、合单支付、签约代扣等。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 4.1.0(11)

#### 导入模块

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

#### PayResult

用户在通用收银台选择支付方式并确认支付后的支付信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.2(14)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.2(14)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| selectedPaymentType | string | 否 | 是 | 用户选择的支付方式。 基于URL跳转三方支付收银台： - wechat_pay：微信支付 - ali_pay：支付宝支付 - 其他（其他为商户申请配置三方支付方式时所申请的相关配置） 基于接口拉起三方支付收银台： - wechat_pay_sdk：微信支付 - ali_pay_sdk：支付宝支付 - 其他（其他为商户申请配置三方支付方式时所申请的相关配置） |
| clientToken | string | 否 | 是 | 客户端凭证。用于校验调用方信息。 |
| nextStep | string | 否 | 是 | 下一步支付流程。 |
| extraInfo | string | 否 | 是 | 保留字段。json string格式。示例为{"selectPayType":"wechat_pay"}。 |
| payload | string | 否 | 是 | 预留信息，在请求接口时，入参如果传递，接口响应中则会原样返回。 说明： 拉起H5支付场景下需要固定传递“AP”。 |

#### PaymentInfo

三方支付拉起通用收银台时传入的支付订单信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.2(14)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.2(14)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| tradeSummary | string | 否 | 是 | 订单的摘要信息。若未填写，默认为空。 |
| amount | number | 否 | 是 | 订单总金额，必须为大于0的整数值，单位：分。传递非取值范围内的值会导致请求异常。 |
| currency | string | 否 | 是 | 货币单位。若未填写，默认为空。 说明： - 不传递则收银台不显示货币单位。 - 传递后收银台可以转换成货币符号则显示货币符号（比如￥），转换不了则显示所传递的值。 |
| extraInfo | string | 否 | 是 | 保留字段。json string格式。若未填写，默认为空。 说明： 商户可以通过保留字段指定支付方式。指定收银台支付方式列表传递内容示例为{"selectPayType":"wechat_pay\|xxx"}。 |

#### PickerResult

三方支付拉起通用收银台时响应给开发者的订单支付信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.2(14)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.2(14)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| selectedPaymentType | string | 否 | 是 | 用户选择的支付方式。 基于URL跳转三方支付收银台： - wechat_pay：微信支付 - ali_pay：支付宝支付 - 其他（其他为商户申请配置三方支付方式时所申请的相关配置） 基于接口拉起三方支付收银台： - wechat_pay_sdk：微信支付 - ali_pay_sdk：支付宝支付 - 其他（其他为商户申请配置三方支付方式时所申请的相关配置） |
| clientToken | string | 否 | 是 | 客户端凭证。用于校验调用方信息。 |

#### BindCardResult

绑卡结果信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.5(17)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.5(17)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| hasBankCard | boolean | 否 | 否 | 用户当前是否有已绑定的银行卡。 - true：是 - false：否 |
| hasJustBoundCard | boolean | 否 | 是 | 用户在拉起绑卡管理页面后是否完成了绑卡。 - true：是 - false：否 |

#### requestPayment

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

该方法提供基础支付、支付并签约等功能，调用方法前请确保网络已连接，调用该方法后会拉起Payment Kit收银台，支付完成后使用Promise异步返回。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 4.1.0(11)

**参数**：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.UIAbilityContext | 是 | UIAbility上下文，不传会报401参数错误。 |
| orderStr | string | 是 | 拉起收银台传入的订单信息，orderStr是json字符串的格式。不传会报401参数错误。示例为{"app_id":"","merc_no":"","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}。 |

**返回值**：

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象，无返回结果。 |

**错误码**：

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1001930000 | The operation was canceled by the user. |
| 1001930001 | Pay failed. |
| 1001930002 | The transaction has been processed. |
| 1001930010 | Duplicate request. |
| 1001930011 | Network connection error. |

**示例**：

示例中的context的获取方式请参见获取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() {
    // 请使用开发者真实的订单信息（orderStr）
    const orderStr = '{"app_id":"***","merc_no":"***","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}';
    paymentService.requestPayment(this.context, orderStr)
      .then(() => {
        // 支付成功
        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

该方法提供基础支付、支付并签约等功能，调用该方法前请确保网络已连接，调用该方法后会拉起Payment Kit收银台，支付完成后通过AsyncCallback回调结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 4.1.0(11)

**参数**：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.UIAbilityContext | 是 | UIAbility上下文，不传会报401参数错误。 |
| orderStr | string | 是 | 拉起收银台传入的订单信息，orderStr是json字符串的格式。不传会报401参数错误。示例为{"app_id":"","merc_no":"","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当支付成功，err为undefined，否则为错误对象。 |

**错误码**：

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1001930000 | The operation was canceled by the user. |
| 1001930001 | Pay failed. |
| 1001930002 | The transaction has been processed. |
| 1001930010 | Duplicate request. |
| 1001930011 | Network connection error. |

**示例**：

示例中的context的获取方式请参见获取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() {
    // 请使用开发者真实的订单信息（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) {
        // 支付失败
        console.error(`failed to pay, error.code: ${error.code}, error.message: ${error.message}`);
        return;
      }
      // 支付成功
      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>

该方法提供签约功能，调用方法前请确保网络已连接，调用该方法后会拉起Payment Kit签约收银台，签约完成后使用Promise异步返回。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.0(12)

**参数**：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.UIAbilityContext | 是 | UIAbility上下文，不传会报401参数错误。 |
| contractStr | string | 是 | 拉起签约收银台入参，contractStr是json字符串的格式。不传会报401参数错误。 |

**返回值**：

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象，无返回结果。 |

**错误码**：

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1001930000 | The operation was canceled by the user. |
| 1001930002 | The transaction has been processed. |
| 1001930003 | Withhold failed. |
| 1001930010 | Duplicate request. |
| 1001930011 | Network connection error. |

**示例**：

示例中的context的获取方式请参见获取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() {
    // 请使用开发者真实的入参信息（contractStr）
    const contractStr = '{"appId":"***","preSignNo":"***"}';
    paymentService.requestContract(this.context, contractStr)
      .then(() => {
        // 签约成功
        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

该方法提供签约功能，调用该方法前请确保网络已连接，调用该方法后会拉起Payment Kit签约收银台，签约完成后通过AsyncCallback回调结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.0(12)

**参数**：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.UIAbilityContext | 是 | UIAbility上下文，不传会报401参数错误。 |
| contractStr | string | 是 | 拉起签约收银台入参，contractStr是json字符串的格式。不传会报401参数错误。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当签约成功，err为undefined，否则为错误对象。 |

**错误码**：

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1001930000 | The operation was canceled by the user. |
| 1001930002 | The transaction has been processed. |
| 1001930003 | Withhold failed. |
| 1001930010 | Duplicate request. |
| 1001930011 | Network connection error. |

**示例**：

示例中的context的获取方式请参见获取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() {
    // 请使用开发者真实的回调函数（contractStr）
    const contractStr = '{"appId":"***","preSignNo":"***"}';
    paymentService.requestContract(this.context, contractStr, (error: BusinessError) => {
      if (error) {
        // 签约失败
        console.error(`failed to sign, error.code: ${error.code}, error.message: ${error.message}`);
        return;
      }
      // 签约成功
      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>

该方法提供拉起通用收银台、跳转三方支付功能，调用方法前请确保网络已连接，用户在通用收银台选择支付方式并确认支付后，使用Promise异步返回。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.2(14)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.2(14)

**参数**：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.UIAbilityContext | 是 | UIAbility上下文，不传会报401参数错误。 |
| orderStr | string | 是 | 拉起收银台或跳转三方支付传入的订单信息。 orderStr是json字符串的格式，不传会报401参数错误。示例为{"app_id":"","merc_no":"","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}。 |
| payload | string | 是 | 预留信息，在请求接口时，入参如果传递，接口响应中则会原样返回。 说明： 拉起华为支付收银台，需传空或空字符。H5支付场景下跳转三方支付收银台需要固定传递“AP”。 |

**返回值**：

| 类型 | 说明 |
| --- | --- |
| Promise<PayResult> | Promise对象。带PayResult返回结果的Promise对象。 说明： 华为支付场景下，PayResult可能返回为空，支付结果以回调通知或查询结果为准。 |

**错误码**：

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1001930000 | The operation was canceled by the user. |
| 1001930001 | Pay failed. |
| 1001930002 | The transaction has been processed. |
| 1001930010 | Duplicate request. |
| 1001930011 | Network connection error. |

**示例**：

示例中的context的获取方式请参见获取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() {
    // 请使用开发者真实的订单信息（orderStr）支付订单。
    // 订单信息示例参考'{"app_id":"***","merc_no":"***","prepay_id":"xxx","timestamp":"1680259863114","noncestr":"1487b8a60ed9f9ecc0ba759fbec23f4f","sign":"****","auth_id":"***"}'
    // 请使用开发者真实的订单信息（orderStr）跳转到第三方支付。
    const orderStr = '{"nextAction":"L","linkUrl":"","scheme":"","clientToken":"***"}';
    paymentService.requestPayment(this.context, orderStr, 'AP')
      .then((payResult: paymentService.PayResult) => {
        // 支付成功
        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>

该方法提供拉起通用收银台功能，调用方法前请确保网络已连接，用户在通用收银台选择支付方式并确认支付后，使用Promise异步返回。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.2(14)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.2(14)

**参数**：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.UIAbilityContext | 是 | UIAbility上下文，不传会报401参数错误。 |
| paymentInfo | PaymentInfo | 是 | 拉起通用收银台传入的支付信息。 |

**返回值**：

| 类型 | 说明 |
| --- | --- |
| Promise<PickerResult> | Promise对象。带PickerResult返回结果的Promise对象。 |

**错误码**：

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1001930000 | The operation was canceled by the user. |
| 1001930001 | Pay failed. |
| 1001930002 | The transaction has been processed. |
| 1001930010 | Duplicate request. |
| 1001930011 | Network connection error. |

**示例**：

示例中的context的获取方式请参见获取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() {
    // 请使用开发者真实的支付信息（paymentInfo）
    const paymentInfo: paymentService.PaymentInfo = {
      tradeSummary: '***交易',
      amount: 100,
      currency: 'CNY',
      extraInfo: '{"***":"***"}'
    }
    paymentService.cashierPicker(this.context, paymentInfo)
      .then((pickerResult: paymentService.PickerResult) => {
        // 支付成功
        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>

该方法提供用户绑卡功能，调用该方法后会拉起Payment Kit用户绑卡页面，绑卡完成后使用Promise异步返回。调用方法前请确保网络已连接。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.5(17)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Payment.PaymentService

**起始版本：** 5.0.5(17)

**参数**：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.UIAbilityContext \| common.UIExtensionContext | 是 | UIAbility上下文，不传会报401参数错误。 |

**返回值**：

| 类型 | 说明 |
| --- | --- |
| Promise<BindCardResult> | Promise对象。带BindCardResult返回结果的Promise对象。 |

**错误码**：

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error.Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1001930000 | The operation was canceled by the user. |
| 1001930011 | Network connection error. |

**示例**：

示例中的context的获取方式请参见获取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) => {
        // 绑卡成功
        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%')
  }
}
```