npm package: @hw-agconnect/pay-harmony
Description: lowcode pay and order js sdk
Latest version: 1.0.0

# AGConnect 支付 SDK

## 业务介绍

此 SDK 提供给鸿蒙 API5-7 版本接入华为聚合支付和低代码订单查询退款等使用

## 前置条件

1. 在准备开发前，你需要在在华为支付商户平台入网
2. 商户成功登录商户平台后，须在证书管理中上传商户证书；上传完商户证书后商户方可进行交易；证书必须与商户号相匹配且是有效的。
3. 开通 AGC 低码服务

## 所需配置

参照[HarmonyOS使用入门](https://developer.huawei.com/consumer/cn/doc/development/AppGallery-connect-Guides/agc-get-started-harmonyos-0000001184684961#section641530103413)
导入“agconnect-services.json”文件并配置agcp插件


1. 打开“entry”应用级根目录的“build.gradle”文件，在“dependencies”中添加如下编译依赖

```
dependencies { implementation 'com.huawei.hms:jsb-ohos-adapter:5.3.0.303' }

```

2. 在 config.json 文件添加如下配置

```
"deviceConfig": { "default": { "allowComponentsProxy": true } }
```

3. 打开“entry”应用级根目录的“package.json”文件，增加如下依赖
   (注意，这只是一个调试版本，最终正式版本号不可以这个为准)。

```
"@hw-agconnect/pay-harmony": "1.0.0-beta"
```

4.打开“entry”应用级根目录的“build.gradle”文件，增加如下依赖

```
implementation "com.huawei.agconnect:agconnect-lowcode-harmony:1.5.2.200"
```

5.在 HarmonyOS 应用“entry/src/main/config.json”的 metaData 节点增加如下属性配置，其中“value”的值为开发者的 OAuth 2.0 客户端 ID（在 AppGallery
Connect 网站点击“我的项目”，在项目列表中找到您的项目，在“项目设置 > 常规”页面的“应用”区域获取“OAuth 2.0 客户端 ID（凭据）：Client ID”的值。

```
"module":{
"package": "com.example.myapplication",
 "name": ".MyApplication",
"mainAbility": "com.example.myapplication.MainAbility",
"deviceType": [],
"distro": {},
"abilities": [],
"js": [],
"metaData":
{
"customizeData":[
{
"name": "com.huawei.hms.client.appid",
"value": "{OAuth Client ID}" // 这里需要把{OAuth Client ID}替换为OAuth 2.0客户端ID
}
]
```

5.在应用的 MyApplication 的 onInitialize 方法初始化 JSB，在 onEnd 方法结束 JSB 模块的使用。

```
public class MyApplication extends AbilityPackage {
    private HmsBridge mHmsBridge;

    @Override
    public void onInitialize() {
        super.onInitialize();
        AGConnectInstance.initialize(this);
        mHmsBridge = HmsBridge.getInstance();
        mHmsBridge.initBridge(this);
    }

    @Override
    public void onEnd() { // 结束JSB
        super.onEnd();
        mHmsBridge.destoryBridge();
    }
}
```

## 接口调用

引入 SDK

```
import payService from '@hw-agconnect/pay-harmony';
```

payService 为一个单例对象，支持接口说明如下

```
   /**
     * 支付功能
     * 当前支持华为聚合支付(预下单、支付、返回支付结果)
     *
     * @param connectorId 连接器id
     * @param preOrderRequest 预下单请求
     * @param paymentMethod 支付方式
     */
    pay(connectorId: string, preOrderRequest: PreOrderRequest, paymentMethod?: PaymentMethod): Promise<OrderResponse>;
    /**
     * 支付功能
     * 当前支持华为聚合支付（支付、返回支付结果）
     *
     * @param connectorId 连接器id
     * @param payOrderInfo 预下单信息
     * @param paymentMethod 支付方式
     */
    payByOrder(connectorId: string, payOrderInfo: PayOrderInfo | any, paymentMethod?: PaymentMethod): Promise<OrderResponse | null>;
    /**
     * 订单退款(发起退款并查询退款状态)
     *
     * @param connectorId 连接器id
     * @param refundOrderRequest 退款请求入参
     */
    refund(connectorId: string, refundOrderRequest: RefundOrderRequest): Promise<QueryRefundOrderResponse>;
    /**
     * 预下单
     *
     * @param connectorId 预下单连接器id
     * @param preOrderRequest preOrderRequest
     */
    preOrder(connectorId: string, preOrderRequest: PreOrderRequest): Promise<PreOrderResponse>;
    /**
     * 查询订单
     *
     * @param connectorId 查询订单连接器id
     * @param mercOrderNo 商户订单号
     */
    queryOrder(connectorId: string, mercOrderNo: string): Promise<OrderResponse>;
    /**
     * 订单退款
     *
     * @param connectorId 订单退款连接器id
     * @param refundOrderRequest 退款请求入参
     */
    refundOrder(connectorId: string, refundOrderRequest: RefundOrderRequest): Promise<RefundOrderResponse>;
    /**
     * 订单退款查询
     *
     * @param connectorId 订单退款查询连接器id
     * @param mercRefundOrderNo 商户退款订单号
     */
    queryRefundOrder(connectorId: string, mercRefundOrderNo: string): Promise<QueryRefundOrderResponse>;
```