Minimal 支付中转 API

minimal 主题是 APay 唯一的支付中转层。APay 负责创建支付订单、按实际币种收款并锁定换算快照。外部中转订单在付款成功后通知 Qingpu;APay 自有钱包充值则在本地入账,绝不再发送下游加款事件。

中转订单不会执行 APay 原有的发卡、订阅或本地充值履约。外部请求统一使用隐藏的 minimal-checkout-recharge 载体商品;可选的来源商品只作为业务上下文保留。

接口

  • POST /api/minimal/checkout/create
  • GET /api/minimal/checkout/consume?token=...
  • GET /api/minimal/checkout/status
  • POST /api/admin/minimal/checkout/orders/{orderId}/retry-notify(管理员)
  • POST /api/orders/topup(登录用户创建 APay 钱包充值)
  • GET /api/users/wallet/topups(登录用户查询充值记录)
  • GET /api/admin/topups 与 POST /api/admin/topups/retry(管理员)

密钥与签名

共享密钥优先读取设置项 minimal_checkout_secret,环境变量 MINIMAL_CHECKOUT_SECRET 作为兜底。两者都未配置时,签名接口返回 503。

create 和 status 请求必须携带:

X-APay-Timestamp: 1785312345678
X-APay-Signature: <hex-hmac-sha256>

时间戳与服务器时间偏差不得超过 5 分钟。请求签名规则:

HMAC_SHA256(secret, timestamp + "\n" + method + "\n" + path_with_sorted_query + "\n" + sha256(raw_body))

method 使用大写;query 按键和值排序并排除 signature 参数;无请求体的 GET 使用空字符串的 SHA-256。

创建中转订单

接口: POST /api/minimal/checkout/create

{
  "externalOrderId": "QP-20260728-0001",
  "productId": 12,
  "amount": 13.75,
  "currency": "USD",
  "sourceAmount": 99,
  "sourceCurrency": "CNY",
  "exchangeRate": 0.13888889,
  "rechargeAmount": 99,
  "rechargeCurrency": "CNY",
  "balanceType": "cash",
  "customerEmail": "buyer@example.com",
  "notifyUrl": "https://qingpu.example.com/api/payment/notify",
  "returnUrl": "https://qingpu.example.com/payment/success",
  "cancelUrl": "https://qingpu.example.com/payment/cancel",
  "productName": "Qingpu Pro 月付",
  "attach": {
    "userId": 1024,
    "businessType": "subscription",
    "channel": "qingpu-web"
  }
}
字段类型必填说明
externalOrderIdstring是Qingpu 业务订单号,也是下游入账幂等键。
productIdnumber否APay 来源商品,仅用于有效性校验和业务上下文。
amountnumber条件必填支付网关实际收取金额,0 元订单传 0;未传 productId 时必须提供。
currencystring否实际支付币种,默认 CNY。
sourceAmountnumber否换算前的原始金额。
sourceCurrencystring否换算前的原始/基础币种。
exchangeRatenumber否下单时锁定的汇率,方向为 amount = sourceAmount * exchangeRate。
rechargeAmountnumber否Qingpu 最终充值或履约使用的金额。
rechargeCurrencystring否Qingpu 的记账/充值币种。
balanceTypecash 或 grant否Qingpu 目标余额池,默认 cash。
customerEmailstring否买家联系邮箱。
notifyUrlstring否支付成功服务端通知地址,默认读取 minimal 后台配置。
returnUrlstring否浏览器支付成功返回地址。
cancelUrlstring否浏览器取消或失败返回地址。
productNamestring否来源商品名称快照。
productDescriptionstring否来源商品描述快照。
productImageUrlstring否来源商品图片快照。
productMetaobject否受信任的来源商品配置快照。
attachobject否状态查询和付款通知中原样返回的业务上下文。

未传 rechargeAmount 时,APay 依次从可信商品配置、sourceAmount、实际支付金额解析。订单创建后不得再按最新后台汇率重新计算到账金额。

响应示例

{
  "code": 0,
  "message": "Checkout order created",
  "data": {
    "orderId": "TU20260728123456AB12CD34",
    "externalOrderId": "QP-20260728-0001",
    "checkoutUrl": "https://apay.example.com/api/minimal/checkout/consume?token=...",
    "amount": 13.75,
    "currency": "USD",
    "sourceAmount": 99,
    "sourceCurrency": "CNY",
    "exchangeRate": 0.13888889,
    "rechargeAmount": 99,
    "rechargeCurrency": "CNY",
    "balanceType": "cash",
    "isFreeOrder": false,
    "reused": false,
    "expiresAt": "2026-07-28T13:05:00.000Z"
  }
}

幂等规则

externalOrderId 在 minimal_checkout 来源内唯一。APay 通过 (orders.source, orders.external_order_id) 唯一索引处理普通重试和并发创建;重复请求返回已有订单和新的 checkoutUrl,并标记 reused: true。

如果重试请求与已有订单的商品、买家、回调地址、实付金额/币种或充值金额/币种冲突,接口返回 409。

实付金额为 0 的订单会直接标记为已支付并立即进入中转履约。响应返回 isFreeOrder: true 和 expiresAt: null;Qingpu 处理通知时仍必须按同一个 externalOrderId 做幂等入账。

Qingpu 也必须使用 externalOrderId 作为充值或履约幂等键。HTTP 重试、超时和响应丢失都不能导致重复入账。

打开支付页

GET /api/minimal/checkout/consume?token=... 仅供浏览器访问。它校验签名令牌、恢复订单对应的 visitor_id Cookie,再跳转到 /payment/{orderId}。Qingpu 服务端不要请求该接口,前端直接打开返回的 checkoutUrl。

查询支付状态

接口: GET /api/minimal/checkout/status

orderId 和 externalOrderId 至少提供一个。响应包含实际支付信息、来源金额与汇率快照、充值口径、通知状态、跳转地址和 attach 业务上下文。

{
  "code": 0,
  "data": {
    "orderId": "TU20260728123456AB12CD34",
    "externalOrderId": "QP-20260728-0001",
    "productId": 12,
    "productName": "Qingpu Pro 月付",
    "amount": 13.75,
    "currency": "USD",
    "sourceAmount": 99,
    "sourceCurrency": "CNY",
    "exchangeRate": 0.13888889,
    "rechargeAmount": 99,
    "rechargeCurrency": "CNY",
    "balanceType": "cash",
    "status": "none",
    "payStatus": "pending",
    "payMethod": "alipay",
    "notify": null,
    "attach": {
      "userId": 1024,
      "businessType": "subscription",
      "channel": "qingpu-web"
    }
  }
}

支付成功通知

支付成功被原子抢占后,APay 把中转订单标记为已交付,并且只选择一个下游通道:

  • APay 自有钱包充值(attach.walletOwner: "apay")只写本地 user_wallets,两个下游通道都不发送。
  • 配置了 notifyUrl 时,以 minimal.checkout.paid 为唯一权威通知。
  • 未配置 notifyUrl 时,才回退到旧的 order.paid 事件总线。
  • 专用通知发送失败时不会切换到旧通道,因为接收方可能已经入账,只是响应丢失。

支付网关回调、主动查单补偿、后台手动确认和 0 元中转订单都遵循相同规则。

X-APay-Event: minimal.checkout.paid
X-APay-Timestamp: 1785312345678
X-APay-Signature: <hex-hmac-sha256>
Content-Type: application/json

出站通知签名:

HMAC_SHA256(secret, timestamp + "\n" + raw_json_body)
{
  "event": "minimal.checkout.paid",
  "timestamp": "2026-07-28T12:40:00.000Z",
  "data": {
    "orderId": "TU20260728123456AB12CD34",
    "externalOrderId": "QP-20260728-0001",
    "amount": 13.75,
    "currency": "USD",
    "sourceAmount": 99,
    "sourceCurrency": "CNY",
    "exchangeRate": 0.13888889,
    "rechargeAmount": 99,
    "rechargeCurrency": "CNY",
    "balanceType": "cash",
    "status": "delivered",
    "payStatus": "paid",
    "tradeNo": "2026072800019988",
    "paidAt": "2026-07-28T12:39:45.000Z",
    "contactEmail": "buyer@example.com",
    "product": {
      "id": 12,
      "name": "Qingpu Pro 月付",
      "type": "subscription"
    },
    "attach": {
      "userId": 1024,
      "businessType": "subscription",
      "channel": "qingpu-web"
    }
  }
}

Qingpu 应先验签,再原子抢占 externalOrderId,并在同一事务内完成钱包或订阅变更。只有事务提交成功后才能返回 2xx。

全额退款通知

经过网关核验的全额退款回调,或管理员登记的全额退款,会向原专用 notifyUrl 发送 minimal.checkout.refunded,沿用支付通知的 HMAC 请求头和数据字段,data.payStatus 为 refunded。APay 自有钱包订单及没有专用地址的订单不发送该事件,退款通知不回退到支付事件总线。重试记录单独保存到 refundNotify,保留 notify 中的支付投递证据。网关回调投递失败返回 500 供网关重试;后台投递失败在保存退款状态后返回 502,再次保存会重试通知。该流程负责登记和通知退款,不会自行向支付厂商发起退款。

接收方必须确认事件头与签名正文的 event 一致、externalOrderId 与 URL 一致,并将原站实付的 sourceAmount/sourceCurrency(缺失时使用结算金额/币种)与本地订单核对。重复通知必须幂等;先发布接收端支持,再启用发送端。网关部分退款不得转换为该全额退款事件。

补发失败通知

管理员可以对“已支付但专用通知尚未成功”的中转订单补发:

POST /api/admin/minimal/checkout/orders/TU20260728123456AB12CD34/retry-notify

接口拒绝未支付订单、未配置专用 notifyUrl 的订单,以及已经通知成功的订单。APay 自有钱包充值会直接返回成功且不发送通知,因为资金已经由本地账本处理。每次外部中转重试都会更新 notify.attemptCount、attemptedAt 和最新 HTTP 结果;minimal 收单中转后台也会对符合条件的失败订单显示同一操作。

APay 钱包充值账本

POST /api/orders/topup 接收支付 currency 与正数 amount。服务端负责计算并锁定钱包到账额度,客户端不能覆盖到账金额、记账币种或余额池。这类订单带有 attach.walletOwner: "apay",并由三张表分别承担事实源职责:

表职责
orders支付网关实付金额、币种与支付状态
topups充值业务状态机以及锁定的实付/到账快照
balance_logs真实钱包资金变动,幂等键为 topup:<orderId> 与 refund:<orderId>

正常状态链为 pending / payment_failed → paid → crediting → credited,退款使用 refunding → refunded。入账失败进入 credit_failed;无法确认结果的中断入账或退款进入 review_required,不会自动重试。只有 credited 的充值才能把对应 APay 订单标记为已交付。

用户通过 GET /api/users/wallet/topups?page=1&pageSize=20 查询记录。管理员通过 GET /api/admin/topups(支持 status 过滤与 search 模糊检索充值单号、客户邮箱或网关交易号)查询全站记录,通过 GET /api/admin/topups/:id 查询单笔充值详情与关联钱包流水,通过 POST /api/admin/topups/retry 补偿可安全重试的入账(支持传递 orderId 单笔重试或 limit 批量重试),或配置携带 Authorization: Bearer <CRON_SECRET> 的 POST /api/cron/reconcile-topups 定时任务。

浏览器返回

成功和取消跳转会附加 orderId、externalOrderId 和 status。浏览器返回只用于页面体验,不能作为支付凭据;Qingpu 必须以签名服务端通知或签名状态查询为准。

免费订单补单兼容

官网结账与共享支付页统一使用 POST /api/orders/complete-free。原管理员接口 POST /api/admin/minimal/checkout/orders/complete-free 保留,仅处理桥接订单,并继续要求原主题后台权限;保留请求与响应结构,付款认领和履约委派给核心实现。管理员操作不受同时存在的前台登录身份限制。原通知重试接口与签名载荷保持不变。