跳到主要内容

查询确认与订单幂等履约

收款完成与履约完成要分别记录。业务服务先认证订单访问权限,再用自己的商户 Key 查询已关联的 Checkout;不能凭前端传来的 status、回跳地址或任意 Checkout ID 发货。

服务端确认流程​

  1. 从本地数据库加载订单、付款尝试、预期金额、币种和关联 Checkout ID。
  2. 调用查询 Checkout,核对身份关联及数值。
  3. open 等待付款、processing 等待确认且不重复引导付款;failed 进入对应订单处理;请求失败表示结果未知。
  4. 对 succeeded 再检查资金异常,并按业务策略决定是否履约。
  5. 在订单级事务中记录支付事实与唯一履约任务,避免并发查询和事件重复触发交付。

同一订单可有多个 Checkout;不能只在 Checkout ID 或 Webhook event ID 上做履约去重。两个付款尝试都成功时,也只能按订单约定履约一次,多余资金另行处理。

可复用 Node 客户端​

下载商户请求与确认示例并保存为 merchant-client.mjs。它使用 Node.js 20+ 自带 fetch,无第三方依赖;固定 HTTPS origin、Bearer 认证、路径编码和已保存的幂等键,不自动重放写请求。

以下是供你的服务端调用的完整函数。savedOrder 必须来自已授权的本地持久化记录;API_BASE 和 API_KEY 由服务端环境提供。该函数查询状态但不执行发货,不包含数据库或队列实现。示例每次查询超时设为 15 秒,这是应用可调整的超时预算,不是平台限制。

import {createMerchantClient, fulfillmentDecision} from './merchant-client.mjs';

// Node.js 20+. Run inside an authenticated server-side order worker.
// Load these values from trusted durable order/attempt storage.
export async function inspectOrder(savedOrder) {
const client = createMerchantClient({
baseUrl: process.env.API_BASE,
apiKey: process.env.API_KEY,
transport: (url, options) => fetch(url, {
...options, signal: AbortSignal.timeout(15_000),
}),
});
const checkout = await client.retrieveCheckout(savedOrder.checkoutId);
return fulfillmentDecision(checkout, {
checkoutId: savedOrder.checkoutId,
orderId: savedOrder.orderId,
amount: savedOrder.amount,
currency: savedOrder.currency,
});
}

fulfillmentDecision 精确比较最多 8 位小数的金额,核对 Checkout/订单/币种绑定。它采用保守示例策略:任意资金异常都返回 review;paidOver 是否允许先履约正常原单,应由你的业务规则独立决定。不能将这个示例策略误认为平台强制退款或状态变更。

把一次决策变成一次交付​

下面是事务流程示意,不是可直接运行的数据库代码:

begin database transaction
lock business order
verify checkout-to-order binding and expected amount/currency
if order already fulfilled: commit and return original result
if verified decision != fulfill: record review/wait outcome and commit
else: record payment fact + unique fulfillment outbox entry for this order
commit
worker delivers the unique outbox operation; retries reuse its business identifier

出库、开通权益或内容交付同样使用可重试且幂等的业务标识。单纯在发货后写 fulfilled=true,可能在“已交付但标记尚未写入”时重复发货;使用事务 outbox 或具备幂等能力的交付接口处理这一窗口。

后台查询与补偿​

由服务端调度查询,设置有界频率、退避、超时和并发。浏览器仅读取你的订单结果。定期用列表接口核对未决订单;未知结果保留待核对状态,不直接创建新支付。

Webhook 开通后可缩短发现延迟,但验签和事件去重不替代资源查询及订单级幂等。通知未开通或遗漏时,保留同一查询补偿机制。

本地演练​

把离线演示和客户端下载到同一目录,执行 node local-demo.mjs。演示使用内存响应,不连接任何服务或真实 Key;会展示 open → fulfill 以及金额不符时的 review,不会执行订单交付。