版权声明：本 Skill 内容来源于上海汇付支付有限公司官方开放平台文档，版权归属上海汇付支付有限公司。如有疑问可咨询汇付支付客服：400-820-2819 / [email protected]

Source: Official Open Platform documentation of Shanghai Huifu Payment Co., Ltd.

Copyright: Shanghai Huifu Payment Co., Ltd.

汇付斗拱支付前端收银台 JS SDK

这个 Skill 只负责前端收银台接入。
服务端预下单、查单和退款，不在这里实现。

想看更细的接入边界，请从 references/README.md 开始，里面补了主链路、createPreOrder 契约、组件模式、回调确认和框架集成提示。

适配版本与复核信息

先分清职责

运行边界

这个 Skill 是前端能力说明。
它不会持有商户私钥，也不会直接请求汇付签名网关。

前端只做两件事：

1. 调用你自己的服务端 createPreOrder 接口
2. 把服务端返回的预下单结果交给 JS SDK

像 HUIFU_RSA_PRIVATE_KEY、HUIFU_RSA_PUBLIC_KEY 这类密钥，只能留在服务端。
浏览器端不要放任何签名密钥。

协议规则入口

如果你要确认签名和异步通知规则，先看共享资料：

• signing-v2.md
• async-notify.md

触发词

• "前端收银台"、"JS SDK"、"HFPay"
• "checkout 组件"、"支付按钮"、"支付宝按钮"、"微信按钮"
• "H5 支付页面"、"PC 收银台"
• "createPreOrder"、"pre_order_type"

参考资料地图

• 主链路先看 references/integration-flow.md
• createPreOrder 返回格式看 references/create-preorder-contract.md
• 组件模式选择看 references/component-modes.md
• 前端 callback 与查单确认边界看 references/callback-and-confirmation.md
• React / Vue / 原生 JS 集成提示看 references/framework-integration-notes.md

适用场景

接入顺序

1. 服务端接好 cashier-order 预下单
2. 前端安装 @dg-elements/js-sdk
3. 定义 createPreOrder
4. 初始化 HFPay
5. 渲染 checkout 或单支付按钮
6. 收到回调后调用 cashier-query 做最终确认

第 1 步：服务端先接好预下单

前端 SDK 不能直接创建支付订单。
你必须先有自己的服务端接口，并且这个接口内部已经调用：

• huifu-dougong-hostingpay-cashier-preorder

服务端接口至少要返回这 4 个字段：

{
  "pre_order_id": "P202604080001",
  "req_seq_id": "202604081530001234",
  "huifu_id": "6666000109133323",
  "req_date": "20260408"
}

第 2 步：安装 SDK

官方文档当前给出的 npm 安装命令是：

npm install @dg-elements/js-sdk

也可以按官方文档下载浏览器版脚本包。

第 3 步：引入 HFPay

官方示例里，初始化入口是 HFPay。
官方文档当前示例安装包名和导入路径写法并不完全一致，示例如下：

import { HFPay } from "dg-element";

如果你的工程里安装后导出入口不同，以实际安装结果为准。
但初始化对象和调用方式，仍然看 HFPay。

第 4 步：判断环境

如果你要做单支付按钮，建议先判断当前环境。
官方示例是直接看浏览器 UA。

function isWXJS() {
  return navigator.userAgent.toLowerCase().includes("micromessenger");
}

function isAliPayJS() {
  return navigator.userAgent.toLowerCase().includes("alipayclient");
}

function isUnionPayJS() {
  return navigator.userAgent.toLowerCase().includes("unionpay");
}

function isWebEnv() {
  return !/Android|webOS|iPhone|iPod|Phone|Mobile|OpenHarmony|BlackBerry/i.test(
    navigator.userAgent
  );
}

第 5 步：定义 createPreOrder

createPreOrder 是整个前端接入的关键。
JS SDK 不帮你生成订单，它只会回调你提供的 createPreOrder 方法。

方法职责

• 向你自己的服务端发起预下单请求
• 服务端内部调用 cashier-order
• 把返回值整理成 JS SDK 需要的格式

返回格式

必须返回下面这几个字段：

• pre_order_id
• req_seq_id
• huifu_id
• req_date

示例

async function createPreOrder(selectedType) {
  const requestBody = {
    trans_amt: document.getElementById("amount").value,
    goods_desc: "会员充值",
    pre_order_type: "1",
    hosting_data: {
      project_id: window.__CHECKOUT_PROJECT_ID__,
      project_title: window.__CHECKOUT_PROJECT_TITLE__,
      callback_url: window.__CHECKOUT_CALLBACK_URL__,
    },
  };

  if (isAliPayJS() || isWXJS() || isUnionPayJS() || isWebEnv()) {
    requestBody.pre_order_type = "1";
  } else if (selectedType === "alipay") {
    requestBody.pre_order_type = "2";
    requestBody.app_data = {
      app_schema: "your-app-schema",
    };
  } else if (selectedType === "wechatpay") {
    requestBody.pre_order_type = "3";
    requestBody.miniapp_data = {
      need_scheme: "Y",
    };
  }

  const response = await fetch("/api/hostingpay/preorder", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(requestBody),
  });

  const data = await response.json();
  return {
    pre_order_id: data.pre_order_id,
    req_seq_id: data.req_seq_id,
    huifu_id: data.huifu_id,
    req_date: data.req_date,
  };
}

pre_order_type 和服务端场景的对应关系

这里一定要和服务端 cashier-order 对齐。

有两个要点：

1. pre_order_type 不是前端随便写的，它决定服务端走哪一类预下单报文
2. 前端一旦切换支付方式，服务端也要跟着切到对应的 app_data 或 miniapp_data

第 6 步：初始化 HFPay

const { error, hfPay } = await HFPay();

if (error) {
  throw error;
}

如果这里初始化失败，直接在前端报错并停止。
不要伪造一个“默认可支付”的降级流程。

第 7 步：渲染 checkout 组件

完整收银台适合一个区域承载多种支付方式。

function callback(result) {
  console.log("checkout callback:", result);
}

const element = hfPay.component("checkout", {
  createPreOrder,
  callback,
});

if (element) {
  element.mount("#checkout-container");
}

第 8 步：渲染单支付按钮

如果你只想展示一个支付按钮，可以直接传组件类型：

• alipay
• wechatpay
• unionpay

const wechatButton = hfPay.component("wechatpay", {
  createPreOrder,
  callback,
});

if (wechatButton) {
  wechatButton.mount("#wechat-button");
}

回调怎么处理

官方公开示例里，回调结构是这样的：

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

建议处理方式

这里最重要的一点是：

前端回调不等于最终支付成功。

页面侧拿到成功提示后，后端仍然要调用：

• huifu-dougong-hostingpay-cashier-query

去查最终状态。

H5 和 PC 的展示差异

前端页面看到的表现会变，但 createPreOrder -> HFPay -> callback -> 查询确认 这条主链路不变。

常见坑

1. 前端直接请求汇付网关。这样做不对。预下单必须走你自己的服务端。
2. 浏览器里放 RSA 私钥。这样做不允许。
3. pre_order_type 和服务端场景没对齐。结果会导致预下单报文和前端拉起方式不匹配。
4. 只看前端回调，不做后端查单。这样很容易把处理中误判成成功。
5. 页面里自己拼假的 pre_order_id。这个值必须来自服务端真实预下单结果。

参考入口

版权声明与联系方式见 copyright-notice.md