交易接入 / 操作与配置

服务端 API 接入:安装 SDK 与验证回调

下载公开 SDK 安装包,从服务端创建订单并严格验证支付通知。

本篇操作教程02 个章节

01 / 准备条件

02 / 分步操作

03 / 结果检查

适用角色
自有业务系统开发者
操作动画
2 段 · 可播放与逐步查看
内容核验
2026-09-23
使用前准备
  • Node.js 18 或以上,及可被公网访问的 HTTPS 服务端。
  • 应用已启用、对应通道配置生效、订阅权益有效;回调网站 Origin 已加入应用白名单。
让 AI 陪你按步骤操作

完整步骤、条件与验收要求。填入自己的业务目标,不要在聊天中粘贴密钥。

查看 / 手动复制完整提示词

关联阅读:

01

从准备到结果确认

查看这段动画的完整步骤
  1. 安装 SDK

    业务服务项目:npm install 本地 TGZ。

    签名凭据只在服务端。

  2. 保存配置

    服务端环境变量:App Secret 不进浏览器。

    首笔网站订单付款与回调金额一致。

  3. 创建订单

    唯一商户单号:金额使用币种最小单位。

    重复通知不能重复开通,浏览器返回不能伪造成功。

  4. 打开收银台

    order.cashierUrl:使用接口返回地址。

    重复通知不能重复开通,浏览器返回不能伪造成功。

  5. 核验通知

    rawBody + verify:应用、金额、币种与状态。

    重复通知不能重复开通,浏览器返回不能伪造成功。

  6. 提交业务

    事务与唯一约束:成功后 2xx + success。

    重复通知不能重复开通,浏览器返回不能伪造成功。

02

首笔验收与排错

查看这段动画的完整步骤
  1. 从业务网站创建待支付订单

    从业务网站创建待支付订单,保存支付平台单号和收银台地址。

    签名凭据只在服务端。

  2. 付款由你自行完成

    付款由你自行完成,确认资金进入预期账户;浏览器返回仅展示处理中并查单,不直接发货。

    首笔网站订单付款与回调金额一致。

  3. 金额/币种一致且只完成一次

    核对 ZOO 支付订单、商户回调和网站业务订单,金额/币种一致且只完成一次。

    重复通知不能重复开通,浏览器返回不能伪造成功。

  4. 回调失败先查 HTTP 状态和响应

    回调失败先查 HTTP 状态和响应;接收端必须直接返回 success,不能重定向至登录页。

    重复通知不能重复开通,浏览器返回不能伪造成功。

  5. 操作 5

    订单、查单、关闭和退款以当前接口文档及通道能力为准;退款需自己的权限、确认和审计,不因为有 SDK 就自动具备金融权限。

    重复通知不能重复开通,浏览器返回不能伪造成功。

详细操作与条件

安装可下载的 SDK

下载 SDK v0.2.0-beta.16(MIT)。此包仅含商户接口客户端及类型,不含系统后台源码或任何配置秘密。下载后在业务服务项目执行:

npm install ./zoo-sdk-0.2.0-beta.16.tgz

API 根地址从商户应用页复制,例如本站域名加 /api/v1。App ID 和 App Secret 保存在服务端环境变量,不能放进浏览器代码。

创建业务订单并打开收银台
import { ZOOClient } from "@zoo/sdk";
const client = new ZOOClient({
  baseUrl: process.env.ZOO_BASE_URL,
  merchant: { appId: process.env.ZOO_APP_ID, appSecret: process.env.ZOO_APP_SECRET }
});
const order = await client.orders.create({
  merchantOrderNo: "YOUR_UNIQUE_BUSINESS_ORDER",
  amount: 100, currency: "CNY", subject: "测试订单",
  notifyUrl: "https://your-business.example/pay/notify",
  returnUrl: "https://your-business.example/pay/result",
  allowedChannels: ["alipay_page"]
});
// 保存 order.platformOrderNo 和 order.cashierUrl,随后跳转到 cashierUrl。

amount 使用币种最小单位,CNY 100 为 ¥1.00。每笔业务使用唯一商户单号;SDK 生成签名和默认幂等键。此片段需由服务端运行,通道换成你已启用的实际通道。

接收通知与防重复开通
const payload = client.notifications.verify({ headers: request.headers, rawBody });
// rawBody 是未经 JSON 重写的原始正文。先验签再处理。
// 在数据库事务中按订单号/通知编号去重,核对 appId、金额、币种与订单成功状态。
// 必要时使用 client.orders.get(platformOrderNo) 再查单。
// 业务提交成功后返回 HTTP 2xx 和纯文本 success。

保存原始请求正文;框架的 JSON parser 不能先丢失原始字符串。使用数据库唯一约束及事务防止重复发货。收到其他应用或金额不符的通知时拒绝处理。通知签名通过也不能省略业务订单与金额核对。

首笔验收与排错
  1. 从业务网站创建待支付订单,保存支付平台单号和收银台地址。
  2. 付款由你自行完成,确认资金进入预期账户;浏览器返回仅展示处理中并查单,不直接发货。
  3. 核对 ZOO 支付订单、商户回调和网站业务订单,金额/币种一致且只完成一次。
  4. 回调失败先查 HTTP 状态和响应;接收端必须直接返回 success,不能重定向至登录页。
  5. 订单、查单、关闭和退款以当前接口文档及通道能力为准;退款需自己的权限、确认和审计,不因为有 SDK 就自动具备金融权限。
操作结果确认
  • 签名凭据只在服务端。
  • 首笔网站订单付款与回调金额一致。
  • 重复通知不能重复开通,浏览器返回不能伪造成功。
本页操作视频

与本页主动画使用同一分镜。视频按 1.5× 导出,32 秒;付款与凭据操作由本人完成。

常见问题
SDK 能直接在前端运行吗?

不能把 App Secret 放在客户端;通过自己的业务服务端调用支付接口。