订单与 Webhook API

虽然 APayShop 提供了完善的前台购物流程,但如果您希望在自己的第三方系统中静默创建一个订单,或者需要接收订单支付成功的状态通知,您可以参考本章节的接口。

创建免登录订单 (Create Guest Order)

允许您在不要求用户注册的情况下,通过接口直接发起一个购买请求。

POST /api/orders/checkout

请求体 (Request Body)

{
  "email": "customer@example.com",
  "locale": "zh-CN",
  "items": [{ "productId": 1, "productNum": 1 }],
  "metaData": {
    "server_ip": "192.168.1.1"
  }
}

参数说明

字段名类型必填说明
itemsarray是一个包含 productId 与正整数 productNum 的商品项;暂不支持多商品合并下单。
emailstring否客户邮箱;登录用户省略时使用账号邮箱。
localestring否当前前台语言,例如 en、zh-CN、ru,用于解析订单结算币种。
payMethodstring否首选支付插件代码;省略时可在支付工作区继续选择。
metaDataobject否服务表单等附加数据;记账字段与币种快照始终由服务端控制。

响应示例

创建成功后,API 返回订单已经锁定的应付金额与结算币种;发起网关支付是后续独立步骤。

{
  "code": 0,
  "message": "订单创建成功",
  "data": {
    "id": "BA20260728123456ABCD1234",
    "amount": 72,
    "currency": "CNY",
    "isFreeOrder": false
  }
}

语言币种解析

全局 currency 是商品定价的基础币种,也是未绑定语言的兜底币种。locale_currency_bindings 可为语言绑定目标结算币种与汇率。汇率方向固定为 1 基础币种 = rate 目标币种;例如基础币种为 USD,中文绑定为 { "currency": "CNY", "rate": 7.2 } 时,10 USD 会转换为 72 CNY。

解析时先匹配完整语言(zh-cn),再匹配主语言(zh),最后回退到基础币种且汇率为 1。下单会把语言、基础金额、目标币种、汇率和转换后金额写入 orders.metaData.currencySnapshot,因此管理员以后修改汇率不会影响历史订单。

orders.amount 与 orders.currency 始终保存支付网关实际收取的换算后金额和币种;内部记账则统一使用锁定快照里的 currencySnapshot.baseAmount 与 currencySnapshot.baseCurrency。订阅价值、履约/外部入账、推广佣金和代理销售等级因此始终使用同一基础币种,不会把不同支付币种直接相加。没有快照的历史订单回退使用原订单金额与币种。

支付插件可以在 configJson 或本地 config.json 中声明 currency(也兼容 sourceCurrency / priceCurrency)。声明后必须与订单币种一致;未声明币种的旧插件仍按币种无关模式兼容。

发起支付

POST /api/payments/initiate 接收 orderId、methodCode 和可选的 locale,调用者必须拥有订单访问权限。执行支付创建脚本前,APay 检查支付方式是否启用、是否允许解析后的前台语言(supportedLocales,空值表示不限制),以及是否支持订单锁定的币种。语言不匹配时返回 { code: 1, message: "当前语言下该支付方式不可用" },不创建支付。已退款或已取消的订单不能再次发起支付。

POST /api/payments/info 接收 orderId 和可选的 locale,沿用相同的订单访问校验。响应 data.methods 中每项仅包含 code、name、iconUrl、渲染后的 content 以及用于标记地区优先网关的 recommendedByGeo。支付通道配置对象与凭据仅供服务端使用;支付 HTML 模板仅替换公共配置白名单字段,key、api_key、apiKey、checkoutSecret、vendorAuthCode、merchantControl、hmacKey 等凭据键一律不会替换到支付 HTML 中。


支付回调沙箱机制 (Webhook Engine)

APayShop 拥有独创的动态支付路由与 Webhook 引擎。

为了不把几十个支付网关(如 Stripe, PayPal, Coinbase, 微信支付等)的乱七八糟的验签代码写死在主项目里,APayShop 实现了 Serverless 风格的回调机制:

  1. 数据库 payment_methods 表中存储了对应网关的 callback.js 纯文本代码。
  2. 当第三方网关发送 Webhook 到我们的 /api/webhooks/[order_id] 时。
  3. 系统会提取出 order_id,查询订单使用的支付渠道。
  4. 取出对应的 callback.js,通过 AsyncFunction 包装执行。这些脚本属于可信管理员代码,不是隔离的安全沙箱。

回调 payload 同时包含从订单记录读取的 order: { id, amount, currency, tradeNo },以及 urlOrderId、body、rawBody、query、headers。这些订单事实不从外部回调 body 提取。主动查单插件必须将远端交易绑定到这些事实,并核对金额与币种;订阅激活状态本身不能作为已扣款凭据。

插件开发规范

如果您需要自己编写一个新的支付插件,您的 callback.js 必须返回一个符合以下规范的对象,主系统才会帮您更新订单状态和自动发货:

// callback.js 示例要求返回的对象结构:
return {
  isSignValid: true, // 验签是否通过
  orderId: "ORD_123456", // 本地订单号
  tradeNo: "ch_123abc", // 第三方网关流水号
  status: "paid", // paid、pending、failed、refunded 或 cancelled
};

这种设计让您可以随时在后台通过网页编辑器修改支付逻辑,实现了真正的支付网关热插拔!

所有回调,包括已支付订单的重复通知,都必须通过验签,且返回的订单号必须与 URL 一致。已验签的 refunded 通知可更新已支付订单,并调用取消佣金、撤销订阅与充值退款处理。未付款续费账单关单不会撤销当前订阅。迟到的失败通知不能覆盖已支付、已退款或已取消订单,关单通知也不能覆盖已退款状态。支付重试使用共享的幂等支付处理器,并返回插件的确认响应(responseBody,默认 success)。

付款订单集成事件

首次履约成功后,APay 通过现有事件规则派发一次 order.paid。载荷包含订单 id、实付 amount 和 currency、基础币种 accountingAmount 和 accountingCurrency、服务端可信的订单 metaData,以及含 type 和 metaData 的 product 快照。钱包入账应使用基础币种金额或服务端计算的 metaData.recharge_amount;实付金额可能是另一种币种。APay 不在该事件中拼装特定服务的交易对象;接收方按订单事实映射自己的账本,并按订单号去重。

完成历史待支付免费订单

POST /api/orders/complete-free 接收 { "orderId": "ORDER_ID" }。这是核心能力,不依赖 Minimal 主题;访问规则与支付页相同:订单所有者或持有支付链接的游客可以完成免费订单,已登录用户不能操作其他用户的订单。会话、委派会话及严格邮箱验证门禁继续生效。

仅允许有限且恰好为 0 的金额,以及 payStatus: pending 的状态被认领。正数、负数、取消、退款及其他未支付状态返回 400;无权访问或不存在的订单返回 403 或 404。并发和重复请求不会重复履约或派发支付事件。已支付免费订单返回 { "code": 0, "data": { "id": "ORDER_ID", "isFreeOrder": true, "alreadyPaid": true } }。

普通 APay 订单走核心履约及 order.paid,中继订单走中继履约及原通知通道。有 notifyUrl 时,通知失败不得切换到第二通道。响应不包含发货内容或客户信息。

付款认领后若履约抛错,接口返回 503,并保留已支付状态。管理员应先核查发货再处理重试;将支付状态改回 pending 可能重复外部副作用。新建零价订单已在创建时完成支付,本接口主要补全历史待支付免费订单。

后台充值记录管理

后台「订单管理 → 充值记录」支持本页多选与详情内单笔操作。GET /api/admin/topups 新增 archive=current|archived|all 筛选,默认 current,并继续支持 status、search、page、pageSize。列表和 GET /api/admin/topups/{id} 均返回 archivedAt、archivedBy、archiveReason、productType 和服务端计算的 managementActions。

POST /api/admin/topups/manage 使用管理员会话或管理员令牌,要求 orders:edit 权限:

{ "action": "archive", "ids": [12, 13], "reason": "已根据原始记录核实支付与权益履约结果" }
  • ids 为 1~50 个正整数充值记录 ID,重复 ID 只处理一次。reason 必填,去除首尾空白后最多 500 字。
  • close:关闭并归档未付款的充值记录,不取消关联订单或支付渠道交易。已付款、已退款、正在处理或支付事实不一致的记录不能关闭。后续真实付款可以恢复该充值的入账处理,继续使用原幂等键。
  • archive:将已核对的 credited、refunded、closed、review_required 记录收起,保留原财务状态与错误证据。历史误归充值、实际属于已履约非充值商品的待支付记录,也可核对后归档。真实充值已付未到账、正在入账/退款以及存在未回收缺口的记录不能归档。
  • restore:只恢复到当前列表,不重新支付、不改变财务状态、不增加余额。

响应为 { "code": 0, "data": { "results": [{ "id": 12, "orderId": "…", "outcome": "updated" }] } }。每笔结果为 updated、unchanged、skipped 或 failed;跳过或失败会携带原因 not_found、not_allowed、changed、failed。处理过程中状态发生变化时跳过该笔,不覆盖新状态。操作日志保存处理人、动作、原因与逐笔结果,包含恢复展示的原因及批次部分失败。

归档结果保存在服务端,其他后台客户端可复用这些接口。已归档的历史非充值记录退出自动重试队列;已关闭的真实充值在后续确认付款时仍可被对账恢复。新的退款在状态变更时同步恢复展示;已完成入账的重复回调不会撤销用户主动归档。该流程不物理删除充值流水,也不修改钱包余额。

部署前先执行增量核心迁移:SQLite 0043_topup_archival、PostgreSQL 0045_topup_archival、MySQL 0039_topup_archival,再放行新版接口。迁移只新增可空字段,不处理存量订单。回归命令为 node scripts/check-topup-ledger.mjs,使用临时 SQLite 测试库。回滚应用时保留新增列;若已执行关闭操作,旧版入账代码不识别 closed,回滚必须保留本次迟到付款恢复逻辑,或在放行旧版入账前按操作日志将相关未付记录恢复到关闭前状态。新版内的“恢复展示”只影响列表可见性。