Repository：https://github.com/huifurepo/dg-js-sdk

简介

收银台 SDK，是基于支付托管模式，商户需开通支付托管功能。SDK 支持支付宝、微信、云闪付等多种支付方式。同时能根据需求高定制化的配置页面样式。封装收银台页面以及独立支付按钮等功能组件，通过 npm 包的形式分发和引入，帮助商户无感对接支付。降低商户接入支付的复杂性。

改变原有支付托管跳转页面的接入方式，只提供支付功能的组件或按钮，允许商户侧自己定制实现收银台页面。实现页面高定制化的需求。

开发者通过创建 'checkout' element 创建页面组件，然后将其渲染到页面上，同时传入 callback 方法用来接收处理事件结果。

• 默认包含支付宝，微信，云闪付三种支付方式。
• 根据环境展示支付方式，支付宝内只展示支付宝，微信内只展示微信，云闪付只展示云闪付。系统默认浏览器展示支付宝与微信。

H5页面效果图

PC页面效果图

流程说明

• 如果是 ATU App 内浏览器访问页面。
  • 如果是微信 app，跳转授权页面，获取 authcode 下单。发起支付。（微信内走公众号支付流程，结果页）
  • 如果是支付宝 app，下单 A_native 正扫 方式，拉起，支付。
  • 如果是云闪付，跳转授权页面，获取 authcode，点击支付按钮，下单，发起支付。
• 如果是手机系统自带浏览器，
  • 选择微信支付，跳转微信托管小程序，完成支付。H5 页面轮询获取支付结果，返回支付结果给调用方。
  • 选择支付宝支付，跳转支付宝，下单 A_native 正扫 方式，拉起，支付。H5 页面轮询获取支付结果，返回支付结果给调用方。
  • 不支持云闪付。
• 如果是PC 端浏览器，展示支付方式对应的支付二维码，用户扫描二维码完成支付。支付逻辑同手机端相同。

接入说明

服务端对接

支付sdk是基于支付托管模式的，商户需开通支付托管功能，并且商户服务端需对接预下单接口，并提供前端接口给前端调用。 接口文档参见 预下单接口

（注意：H5/PC页面预下单选择要根据环境判断，如果是ATU app内预下单pre_order_type = 1； 如果是在商户自己App，或者是系统默认浏览器里面是通过跳转小程序的方式完成支付的，所以如果在非ATU环境下，选择微信的话 pre_order_type=3，选支付宝 预下单 pre_order_type= 2）

前端对接准备

1，远程下载并安装sdk

npm install dg-element 

或下载sdk 包 1.0.0

2，引入sdk

import { HFPay } from 'dg-js-sdk';

3，判断环境

如渲染单一支付按钮组件，需先判断当前环境是否支持

/**
 * @Description: 判断是否是微信浏览器
 */
function isWXJS() {
  return navigator && navigator.userAgent.toLowerCase().indexOf('micromessenger') > 0;
}

/**
 * @Description: 判断是否是支付宝浏览器
 */
function isAliPayJS() {
  return navigator && navigator.userAgent.toLowerCase().indexOf('alipayclient') > 0;
}

/**
 * @Description: 判断是否是银联浏览器
 */
function isUnionPayJS() {
  return navigator && navigator.userAgent.toLowerCase().indexOf('unionpay') > 0;
}

/**
 * @Description: 判断是否是web环境
 */
function isWebEnv() {
  return !/Android|webOS|iPhone|iPod|Phone|Mobile|OpenHarmony|BlackBerry/i.test(navigator.userAgent);
}

4，定义预下单方法

通过服务端接口获取预下单号，定义方法，供后续传入sdk，sdk 内会调用该方法获取预下单号。 以下为代码示例，具体调用以商户侧为准，但返回数据格式需与示例一致。需包含 pre_order_id、huifu_id、req_seq_id、req_date

const createPreOrder = async function (selectedType) {
  // 增加loading 弹框
  document.getElementById('loadingMask').classList.remove('hide');
  const requestBody = {
    huifu_id: '6666000109133323',
    req_seq_id: Date.now().toString(),
    trans_amt: document.getElementById('element-amount').value,
    time_expire: '300',
    pre_order_type: '1',
    goods_desc: '无线鼠标静音无声笔记本台式电脑',
    hosting_data: {
      project_title: 'DEMO演示-无模板',
      project_id: 'PROJECTID2023092518673961',
      callback_url: 'http://paas.huifutest.com/checkout/demo/h5/jsSDKDemo.html',
    }
  };

  if (isAliPayJS() || isWXJS() || isUnionPayJS() ) {

    requestBody.pre_order_type = '1';
  } else if (selectedType === 'alipay') {
    requestBody.pre_order_type = '2';
    requestBody.app_data = {
      app_schema: 'app_schema',
    }
  } else if (selectedType === 'wechatpay') {
    requestBody.pre_order_type = '3';
    requestBody.miniapp_data = {
      need_scheme: 'Y',
    }
  }

  try {
    const response = await fetch(`https://checkoutbff.cloudpnr.com/v1/payment/pre/create`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json', // 建議加上 Header
      },
      body: JSON.stringify(requestBody),
    });

    const data = await response.json();
    console.log('預下单结果:', data);
    // 隐藏loading 弹框
    document.getElementById('loadingMask').classList.add('hide');
    loadingFlag = false;
    return {
      pre_order_id: data.json_data.pre_order_id,
      req_seq_id: data.json_data.req_seq_id,
      huifu_id: data.json_data.huifu_id,
      req_date: data.json_data.req_date,
    };
  } catch (err) {
    // 隐藏loading 弹框
    $('#loadingMask').hide();
    console.error('預下單失敗:', err);
    // 將錯誤向上拋出，讓調用者也能處理
    throw err;
  }
}   

5，创建收银台 element，将组件渲染到页面上

• 方法调用

const { error, hfPay } = await HFPay();
hfPay.component(elementName,{
        createPreOrder: createPreOrder,
        callback:callback
    });

• 参数说明 |参数 | 类型 |说明 | |:--------|:------------|:-------------| | elementName | 字符串 | element 类型，checkout| | createPreOrder | function | 创建预下单的方法，需返回预下单号，具体参见调用示例| | callback | function | 回调方法，一般处理报错信息|

调用示例：

function callback(result) {
    console.log('callback  返回' + JSON.stringify(result));
    // {"type":"payment_data","data":{"transStat":"1","huifuId":"6666000109133323","reqSeqId":"1753150933645","reqDate":"20250722","respDesc":"操作成功"}}
}
let element = hfPay.component('checkout', 
    {
        createPreOrder: createPreOrder,
        callback:callback
    });
if (element) {
    element.mount('#element-container');
} else {
   	console.log(`App: SDK 未能創建組件`);
}	

6，创建单支付按钮 element，将组件渲染到页面上

除了创建整个checkout组件，还可以创建单支付按钮组件，支持支付宝、微信、云闪付三种支付方式

• 方法调用

const { error, hfPay } = await HFPay();
hfPay.component(type, {
        createPreOrder: createPreOrder,
        callback:callback
    });

• 参数说明 |参数 | 类型 |说明 | |:--------|:------------|:-------------| | elementypetName | 字符串 | 单支付按钮类型，枚举值，alipay、wechatpay、unionpay| | createPreOrder | function | 创建预下单的方法，需返回预下单号，具体参见调用示例| | callback | function | 回调方法，一般处理报错信息|

7，处理回调

{ 
  "type":"payment_data",
  "data":{
    "transStat":"1",
    "huifuId":"6666000109133323",
    "reqSeqId":"1753150933645",
    "reqDate":"20250722",
    "respDesc":"操作成功"
  }
}   

常见问题

Q1：如何给支付按钮定制样式

A：可直接通过按钮class name 进行css 样式定制

Q2：微信支付宝是怎么实现支付的

A：如果在ATU 环境中，点击支付，页面会跳转到支付页面。如果在非ATU 环境中，点击支付，会拉起小程序进行后续支付操作。

SDK版本记录