回调与验签

先把回调地址、校验方式和入账规则定下来。

这页按接入顺序说明回调怎么配、怎么验、哪些状态算成功，以及重复通知怎么处理。

查看计费指南查看安全指南

API 文档/回调与验签

回调流程

先校验，再入账。

统一回调入口是 `/api/payments/callback/[provider]`。第三方通知先打到这里，再由服务端决定是否更新订单状态。

通知地址按 provider 维度区分

统一回调入口是 `/api/payments/callback/{provider}`，例如 `alipay`、`wxpay`、`stripe`。

回调先验签，再解析 JSON

只有通过 token 或签名校验的回调才会继续处理；非法 JSON 或缺少订单号会直接返回 400。

只有成功支付状态才会入账

当前默认接受 `SUCCESS`、`PAID`、`TRADE_SUCCESS` 三类状态，其他状态只确认收到，不执行充值入账。

推荐回调 body

{
  "orderNo": "PO202604060001",
  "thirdPartyOrderNo": "202604060900001234",
  "status": "SUCCESS"
}

校验方式

测试用令牌，生产优先签名。

生产环境至少启用一种校验方式。签名更稳，令牌更适合测试或过渡期。

令牌模式适合测试阶段

通过 `x-tokenai-callback-token` 头校验。
适合本地测试或临时网关接入，但生产更推荐签名模式。

Signature 模式适合正式接入

使用 `x-tokenai-timestamp` 和 `x-tokenai-signature` 头。
签名内容为 `${provider}.${timestamp}.${rawBody}` 的 HMAC-SHA256。
默认校验时间窗由 `PAYMENT_CALLBACK_MAX_AGE_SECONDS` 控制。

Disabled 仅适合未接生产前的占位

如果没有配置令牌或签名密钥，回调校验模式会是 `disabled`。
这种状态不适合上线使用，接正式支付前应至少启用令牌或签名之一。

令牌模式回调示例

curl -X POST "https://api.ciyuan.com/api/payments/callback/alipay" \
  -H "Content-Type: application/json" \
  -H "x-tokenai-callback-token: $PAYMENT_CALLBACK_TOKEN" \
  -d '{
    "orderNo": "PO202604060001",
    "thirdPartyOrderNo": "202604060900001234",
    "status": "SUCCESS"
  }'

Signature 模式回调示例

BODY='{"orderNo":"PO202604060001","thirdPartyOrderNo":"202604060900001234","status":"SUCCESS"}'
TIMESTAMP=$(date +%s%3N)
SIGNATURE=$(printf '%s' "alipay.${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "$PAYMENT_CALLBACK_SIGNING_SECRET" -binary | xxd -p -c 256)

curl -X POST "https://api.ciyuan.com/api/payments/callback/alipay" \
  -H "Content-Type: application/json" \
  -H "x-tokenai-timestamp: ${TIMESTAMP}" \
  -H "x-tokenai-signature: ${SIGNATURE}" \
  -d "${BODY}"

不是任何通知都代表到账成功。

当前默认把 `SUCCESS`、`PAID`、`TRADE_SUCCESS` 视为成功状态，其他状态只确认收到，不触发入账。

回调 body 至少应包含 `orderNo`，推荐同时传 `thirdPartyOrderNo` 和 `status`。
当前会把 `status` 统一转大写后判断，因此支付网关原始字段最好在你的服务端先归一化。
非成功状态不会报错中断，而是返回 `acknowledged: true`，表示平台已收到但不会执行入账。

幂等与入账

重复通知是常态，幂等入账是必须项。

到账逻辑会先检查订单状态，再在同一个事务里更新订单、余额和流水，避免重复回调导致重复入账。

幂等处理原则

同一订单重复回调时，不会重复加余额；如果订单已经是 `PAID`，接口会返回 `alreadyPaid: true`。
真正的钱包变更、订单状态修改和账本写入在同一个事务里完成，避免部分成功。
建议接入方把第三方回调重试视为正常现象，而不是把重复通知当异常。

推荐接法

第三方网关先回调到你的支付中台或服务端，再由你的服务端转发到平台支付回调入口。
保留第三方订单号和原始回调日志，便于后续对账、人工审核和问题追溯。
如果支付链路很长，优先保证“到账幂等”正确，再去优化用户侧的状态刷新速度。

回调与验签

先把回调地址、校验方式和入账规则定下来。

这页按接入顺序说明回调怎么配、怎么验、哪些状态算成功，以及重复通知怎么处理。

查看计费指南查看安全指南

API 文档/回调与验签

回调流程

先校验，再入账。

统一回调入口是 `/api/payments/callback/[provider]`。第三方通知先打到这里，再由服务端决定是否更新订单状态。

通知地址按 provider 维度区分

统一回调入口是 `/api/payments/callback/{provider}`，例如 `alipay`、`wxpay`、`stripe`。

回调先验签，再解析 JSON

只有通过 token 或签名校验的回调才会继续处理；非法 JSON 或缺少订单号会直接返回 400。

只有成功支付状态才会入账

当前默认接受 `SUCCESS`、`PAID`、`TRADE_SUCCESS` 三类状态，其他状态只确认收到，不执行充值入账。

推荐回调 body

{
  "orderNo": "PO202604060001",
  "thirdPartyOrderNo": "202604060900001234",
  "status": "SUCCESS"
}

校验方式

测试用令牌，生产优先签名。

生产环境至少启用一种校验方式。签名更稳，令牌更适合测试或过渡期。

令牌模式适合测试阶段

通过 `x-tokenai-callback-token` 头校验。
适合本地测试或临时网关接入，但生产更推荐签名模式。

Signature 模式适合正式接入

使用 `x-tokenai-timestamp` 和 `x-tokenai-signature` 头。
签名内容为 `${provider}.${timestamp}.${rawBody}` 的 HMAC-SHA256。
默认校验时间窗由 `PAYMENT_CALLBACK_MAX_AGE_SECONDS` 控制。

Disabled 仅适合未接生产前的占位

如果没有配置令牌或签名密钥，回调校验模式会是 `disabled`。
这种状态不适合上线使用，接正式支付前应至少启用令牌或签名之一。

令牌模式回调示例

curl -X POST "https://api.ciyuan.com/api/payments/callback/alipay" \
  -H "Content-Type: application/json" \
  -H "x-tokenai-callback-token: $PAYMENT_CALLBACK_TOKEN" \
  -d '{
    "orderNo": "PO202604060001",
    "thirdPartyOrderNo": "202604060900001234",
    "status": "SUCCESS"
  }'

Signature 模式回调示例

BODY='{"orderNo":"PO202604060001","thirdPartyOrderNo":"202604060900001234","status":"SUCCESS"}'
TIMESTAMP=$(date +%s%3N)
SIGNATURE=$(printf '%s' "alipay.${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "$PAYMENT_CALLBACK_SIGNING_SECRET" -binary | xxd -p -c 256)

curl -X POST "https://api.ciyuan.com/api/payments/callback/alipay" \
  -H "Content-Type: application/json" \
  -H "x-tokenai-timestamp: ${TIMESTAMP}" \
  -H "x-tokenai-signature: ${SIGNATURE}" \
  -d "${BODY}"

不是任何通知都代表到账成功。

当前默认把 `SUCCESS`、`PAID`、`TRADE_SUCCESS` 视为成功状态，其他状态只确认收到，不触发入账。

回调 body 至少应包含 `orderNo`，推荐同时传 `thirdPartyOrderNo` 和 `status`。
当前会把 `status` 统一转大写后判断，因此支付网关原始字段最好在你的服务端先归一化。
非成功状态不会报错中断，而是返回 `acknowledged: true`，表示平台已收到但不会执行入账。

幂等与入账

重复通知是常态，幂等入账是必须项。

到账逻辑会先检查订单状态，再在同一个事务里更新订单、余额和流水，避免重复回调导致重复入账。

幂等处理原则

同一订单重复回调时，不会重复加余额；如果订单已经是 `PAID`，接口会返回 `alreadyPaid: true`。
真正的钱包变更、订单状态修改和账本写入在同一个事务里完成，避免部分成功。
建议接入方把第三方回调重试视为正常现象，而不是把重复通知当异常。

推荐接法

第三方网关先回调到你的支付中台或服务端，再由你的服务端转发到平台支付回调入口。
保留第三方订单号和原始回调日志，便于后续对账、人工审核和问题追溯。
如果支付链路很长，优先保证“到账幂等”正确，再去优化用户侧的状态刷新速度。

页面加载中

先把回调地址、校验方式和入账规则定下来。

先校验，再入账。

测试用令牌，生产优先签名。

不是任何通知都代表到账成功。

重复通知是常态，幂等入账是必须项。

先把回调地址、校验方式和入账规则定下来。

先校验，再入账。

测试用令牌，生产优先签名。

不是任何通知都代表到账成功。

重复通知是常态，幂等入账是必须项。