SILVERCLOUD / 技术文章
可信的支付确认:面向应用和网站的服务端检查清单
顾客点了“支付”,看到一个绿色对勾,随手关掉了应用。这笔订单付款了吗?大概付了。但涉及钱,“大概”远远不够。那个对勾只说明某台设备走完了一段流程。钱到底有没有转出,只有支付服务商知道;您的服务器必须直接从服务商那里得到答案,而且要通过一条别人无法伪造的渠道。
这份检查清单涵盖支付状态、服务端确认、安全重试、退款、对账和测试,适用于银行卡、电子钱包和二维码转账。
成功页面不等于支付确认
付款完成后,顾客会被带回您的网站或应用,URL 里常带着 ?status=success&order=1042 这样的参数。把它当作凭证,会在三个地方出问题:
- 谁都能改。 在浏览器里把
failed改成success,几秒钟的事。 - 可能根本不会加载。 顾客关掉标签页、手机断网,或者银行 App 没有跳转回来;支付已经成功,您的服务器却毫不知情。
- 可能比钱先到。 有些支付方式,尤其是银行转账,在顾客操作完成后仍会处于待处理状态。
返回页应显示“正在确认支付”,并向您自己的服务器查询;服务器只相信经过验证的来源。客户端永远不能决定一笔订单是否已支付。
一笔支付的状态
明确地为支付建模,而不是只用一个 paid 标志:
- 已创建:已在服务商处登记,顾客尚未付款。
- 待处理:顾客已经操作或转账正在进行,结果尚未确定。
- 成功:服务商确认款项。
- 失败:被拒绝、被取消或被拦截。
- 已过期:支付时限已过,没有结果。
- 部分退款与全额退款:成功后退回部分或全部款项。
银行卡还可能有“已授权、未请款”的状态,之后还可能出现争议(拒付)。把允许的状态转换写进代码:已创建可以变为待处理;已创建或待处理可以变为成功、失败或已过期;成功可以变为部分退款或全额退款,部分退款之后还可以继续退款;任何状态都不会回到已创建或待处理。除此之外的变化,要么是 bug,要么需要人工复核。
在服务端确认,来源必须可验证
可信的来源有两个,稳健的集成会同时使用。
带签名的 Webhook。 发生事件时,服务商会调用您的接口;大多数服务商会用双方共享的密钥为每个请求签名,通常是对原始请求体计算 HMAC-SHA256,并常常带上时间戳。您的处理程序应当:
- 按收到时的原样读取原始请求体。先解析 JSON 再重新序列化,可能改变空白、转义或键的顺序,签名就对不上了。
- 自行计算 HMAC,并用恒定时间比较与请求头中的签名比对。普通的字符串比较在第一个不同的字符处就会停止,这个时间差可能泄露正确签名的信息。
- 拒绝超出短时间窗口的时间戳(常见做法是五分钟),让被截获的请求无法事后重放;时间窗口内的重放,则由按事件 ID 去重来拦截。
- 将金额、币种和订单号与您创建的订单核对。签名有效只能证明消息是谁发的,不能证明顾客为正确的订单付了正确的金额。金额以货币最小单位的整数存储,不要用浮点数。
服务商的 API。 服务器用您的密钥按 ID 查询这笔支付。这可以弥补迟到或丢失的 Webhook;有些团队干脆只把 Webhook 当作信号,收到后再去查询当前状态。
API 密钥和 Webhook 签名密钥只放在服务器上,不进应用安装包,也不进代码仓库,并且要能在不停机的情况下轮换。
幂等:同一事件来两次,什么都不会改变
大多数服务商按“至少一次”的方式投递 Webhook:您的接口超时或返回错误,事件就会重发,有时会重发多次。重复是常态,所以处理逻辑必须是幂等的。
- 按事件 ID 去重。 已处理的事件 ID 存在唯一约束之下,重复投递不会改变任何东西。
- 一个事务,一次更新。 在同一个数据库事务里记录事件 ID 并修改订单状态;任何一步失败都会一起回滚,重试时从干净的状态开始。更新语句要带条件(
WHERE status = 'pending'),这样同时到达的 Webhook 和 API 查询不会把同一订单处理两次。 - 创建支付和退款时使用幂等键。 如果服务商支持,就用您自己的支付尝试 ID 生成幂等键;超时后重试会拿到原来的结果,而不会重复扣款。如果不支持,先用唯一的参考号保存您自己的记录,重试前先按参考号查询。
- 事件可能乱序。 投递顺序通常不受保证,成功事件可能晚于退款事件到达。按状态转换规则处理,而不是用最后到达的事件覆盖,拿不准时就查询当前状态。
- 退避重试。 对超时、连接错误、429 和 5xx 响应进行重试,采用指数退避加随机抖动,并限制次数。参数校验类错误不要重试。
- 超时意味着结果未知,而不是失败。 款项可能已经扣了,要通过查询来确认。
- 定时处理过期。 定时任务找出超过时限仍在待处理的支付,先向服务商查询,再标记为已过期。过期之后才到的成功(银行转账确实会出现这种情况),按事先约定的规则转人工复核或退款。
Webhook 要快速响应:保存、提交、返回 2xx,发邮件、发货这类慢操作放进队列。处理程序太慢会导致超时,而超时会带来更多重复。
落到代码上
下面是一个用 TypeScript 写的最小处理程序,基于 Node.js 和 PostgreSQL。请求头名称、签名编码和被签名的字符串因服务商而异,但整体结构不变。
import { createHmac, timingSafeEqual } from "node:crypto";
import { Pool } from "pg";
const pool = new Pool(); // reads the PG* environment variables
const SECRET = process.env.PAYMENT_WEBHOOK_SECRET!; // server-side only, never in the app
export async function handlePaymentWebhook(req: Request): Promise<Response> {
const raw = Buffer.from(await req.arrayBuffer()); // the exact bytes, before any JSON parsing
const timestamp = req.headers.get("x-signature-timestamp") ?? "";
const received = Buffer.from(req.headers.get("x-signature") ?? "", "hex");
const expected = createHmac("sha256", SECRET).update(`${timestamp}.`).update(raw).digest();
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300; // Unix seconds, 5 minutes
if (!fresh || received.length !== expected.length || !timingSafeEqual(received, expected)) {
return new Response("invalid signature", { status: 400 });
}
const event = JSON.parse(raw.toString("utf8"));
const db = await pool.connect();
try {
await db.query("BEGIN");
// event_id is the primary key: a repeated delivery inserts nothing.
const inserted = await db.query(
"INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING", [event.id]);
if (inserted.rowCount === 1 && event.type === "payment.succeeded") {
// Only pending -> paid, and only if amount and currency match the order.
const paid = await db.query(
`UPDATE orders SET status = 'paid', paid_at = now()
WHERE id = $1 AND status = 'pending' AND amount = $2 AND currency = $3`,
[event.data.order_id, event.data.amount, event.data.currency]);
if (paid.rowCount === 0) await db.query("INSERT INTO payment_review (event_id) VALUES ($1)", [event.id]);
}
await db.query("COMMIT");
return new Response("ok");
} catch {
await db.query("ROLLBACK");
return new Response("retry later", { status: 500 }); // the provider retries
} finally {
db.release();
}
}如果没有匹配的待处理订单(已经支付、已过期,或金额不符),事件会进入复核表,而不是凭空消失。
退款、对账与审计追踪
退款是独立的记录,关联到原支付,有自己的状态:退款同样可能处于待处理状态或失败。多次部分退款的总额绝不能超过已扣款金额。发起退款请求时带上幂等键,只有在服务商确认后才修改订单状态。
每日对账能兜住其他环节漏掉的问题。每天拉取服务商前一天的交易报表或结算报表,按服务商的交易 ID 把每一行与您的记录对上,再比对金额、币种和状态。常见的差异有:
- 服务商显示已支付,您的系统仍是待处理:Webhook 丢了,有位顾客付了钱还在等。
- 您的系统显示已支付,服务商查无此单:bug 或滥用,最紧急的一类。
- 金额或状态不一致:漏记的部分退款,或者把总额、手续费和净结算额混为一谈。
所有差异进入差异队列,有负责人、有处理说明,绝不悄悄修掉。注意报表的截止时间:接近午夜的支付,可能被双方记在不同的日期。
审计追踪。 保存每一条原始 Webhook,连同请求头和验签结果,以便重放;同时保存只追加的状态变更历史:从哪个状态、到哪个状态、何时、由哪个事件、任务或人员触发。日志里绝不记录密钥或完整卡号;使用服务商托管的支付页面或嵌入式支付输入框时,卡号根本不会到达您的服务器。
告警应在以下情况触发:验签失败激增、处理出错、支付卡在待处理、退款失败、对账不一致、成功率骤降。
测试失败路径,而不只是顺利路径
在服务商的沙箱或测试模式下使用测试密钥,然后:
- 重放 Webhook。 把真实的沙箱事件存为测试数据;同一事件发两次、打乱顺序、改动请求体中的一个字节、使用过期的时间戳。
- 注入故障。 在数据库提交之后、返回 2xx 之前终止进程:服务商会重发,而任何事情都不能发生两次。让数据库断开一分钟。给调用服务商的请求加上延迟,直到触发您的超时。
- 滥用客户端。 连点两次“支付”,在跳转前关闭浏览器,用伪造的参数打开返回 URL。
上线前检查清单
- 订单只能通过已验证的 Webhook 或服务端 API 查询变为已支付。
- 基于原始请求体、以恒定时间比较验证签名;过期的时间戳一律拒绝。
- 金额、币种和订单号都与订单核对。
- 事件 ID 唯一;重复投递返回 2xx,且没有副作用。
- 事件记录与状态变更在同一事务中提交,更新语句带条件。
- 创建支付和退款都使用幂等键,或按自有参考号查询。
- 状态转换在代码中定义;迟到的事件不能让订单状态倒退。
- Webhook 接口在服务商的超时时间内响应;慢操作进队列。
- 对外调用设有超时,重试有上限,并采用退避与抖动。
- 待处理支付经状态查询后按计划过期;过期后才到的成功有明确的处理路径。
- 部分退款不会超过已扣款金额。
- 每天运行对账,每一项差异都有负责人。
- 保留原始 Webhook 和状态历史;日志中没有密钥或完整卡号。
- 告警覆盖验签失败、处理错误、卡住的支付和对账差异。
silvercloud 是一支外包开发团队。我们为合作企业在应用和网站中构建这一层,从结账、Webhook 到退款和对账,也按合作方的需求开发支付网关系统,完成后交付给对方团队运营。如果您正在规划支付集成,欢迎通过 silvercloud.city 发送需求简报。