交易接入 / 操作与配置
服务端 API 接入:安装 SDK 与验证回调
下载公开 SDK 安装包,从服务端创建订单并严格验证支付通知。
01 / 准备条件
02 / 分步操作
03 / 结果检查
使用前准备
- Node.js 18 或以上,及可被公网访问的 HTTPS 服务端。
- 应用已启用、对应通道配置生效、订阅权益有效;回调网站 Origin 已加入应用白名单。
让 AI 陪你按步骤操作
完整步骤、条件与验收要求。填入自己的业务目标,不要在聊天中粘贴密钥。
查看 / 手动复制完整提示词
关联阅读:
01从准备到结果确认
查看这段动画的完整步骤
- 安装 SDK
业务服务项目:npm install 本地 TGZ。
签名凭据只在服务端。
- 保存配置
服务端环境变量:App Secret 不进浏览器。
首笔网站订单付款与回调金额一致。
- 创建订单
唯一商户单号:金额使用币种最小单位。
重复通知不能重复开通,浏览器返回不能伪造成功。
- 打开收银台
order.cashierUrl:使用接口返回地址。
重复通知不能重复开通,浏览器返回不能伪造成功。
- 核验通知
rawBody + verify:应用、金额、币种与状态。
重复通知不能重复开通,浏览器返回不能伪造成功。
- 提交业务
事务与唯一约束:成功后 2xx + success。
重复通知不能重复开通,浏览器返回不能伪造成功。
02首笔验收与排错
查看这段动画的完整步骤
- 从业务网站创建待支付订单
从业务网站创建待支付订单,保存支付平台单号和收银台地址。
签名凭据只在服务端。
- 付款由你自行完成
付款由你自行完成,确认资金进入预期账户;浏览器返回仅展示处理中并查单,不直接发货。
首笔网站订单付款与回调金额一致。
- 金额/币种一致且只完成一次
核对 ZOO 支付订单、商户回调和网站业务订单,金额/币种一致且只完成一次。
重复通知不能重复开通,浏览器返回不能伪造成功。
- 回调失败先查 HTTP 状态和响应
回调失败先查 HTTP 状态和响应;接收端必须直接返回 success,不能重定向至登录页。
重复通知不能重复开通,浏览器返回不能伪造成功。
- 操作 5
订单、查单、关闭和退款以当前接口文档及通道能力为准;退款需自己的权限、确认和审计,不因为有 SDK 就自动具备金融权限。
重复通知不能重复开通,浏览器返回不能伪造成功。
详细操作与条件
安装可下载的 SDK
下载 SDK v0.2.0-beta.16(MIT)。此包仅含商户接口客户端及类型,不含系统后台源码或任何配置秘密。下载后在业务服务项目执行:
npm install ./zoo-sdk-0.2.0-beta.16.tgzAPI 根地址从商户应用页复制,例如本站域名加 /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 不能先丢失原始字符串。使用数据库唯一约束及事务防止重复发货。收到其他应用或金额不符的通知时拒绝处理。通知签名通过也不能省略业务订单与金额核对。
首笔验收与排错
- 从业务网站创建待支付订单,保存支付平台单号和收银台地址。
- 付款由你自行完成,确认资金进入预期账户;浏览器返回仅展示处理中并查单,不直接发货。
- 核对 ZOO 支付订单、商户回调和网站业务订单,金额/币种一致且只完成一次。
- 回调失败先查 HTTP 状态和响应;接收端必须直接返回 success,不能重定向至登录页。
- 订单、查单、关闭和退款以当前接口文档及通道能力为准;退款需自己的权限、确认和审计,不因为有 SDK 就自动具备金融权限。
操作结果确认
- 签名凭据只在服务端。
- 首笔网站订单付款与回调金额一致。
- 重复通知不能重复开通,浏览器返回不能伪造成功。
本页操作视频
与本页主动画使用同一分镜。视频按 1.5× 导出,32 秒;付款与凭据操作由本人完成。
常见问题
SDK 能直接在前端运行吗?
不能把 App Secret 放在客户端;通过自己的业务服务端调用支付接口。