silvercloud工作室首页 ↗
中文

SILVERCLOUD / 技术文章

可信的支付确认:面向应用和网站的服务端检查清单

阅读约 8 分钟

顾客点了“支付”,看到一个绿色对勾,随手关掉了应用。这笔订单付款了吗?大概付了。但涉及钱,“大概”远远不够。那个对勾只说明某台设备走完了一段流程。钱到底有没有转出,只有支付服务商知道;您的服务器必须直接从服务商那里得到答案,而且要通过一条别人无法伪造的渠道。

这份检查清单涵盖支付状态、服务端确认、安全重试、退款、对账和测试,适用于银行卡、电子钱包和二维码转账。

成功页面不等于支付确认

付款完成后,顾客会被带回您的网站或应用,URL 里常带着 ?status=success&order=1042 这样的参数。把它当作凭证,会在三个地方出问题:

  • 谁都能改。 在浏览器里把 failed 改成 success,几秒钟的事。
  • 可能根本不会加载。 顾客关掉标签页、手机断网,或者银行 App 没有跳转回来;支付已经成功,您的服务器却毫不知情。
  • 可能比钱先到。 有些支付方式,尤其是银行转账,在顾客操作完成后仍会处于待处理状态。

返回页应显示“正在确认支付”,并向您自己的服务器查询;服务器只相信经过验证的来源。客户端永远不能决定一笔订单是否已支付。

一笔支付的状态

明确地为支付建模,而不是只用一个 paid 标志:

  • 已创建:已在服务商处登记,顾客尚未付款。
  • 待处理:顾客已经操作或转账正在进行,结果尚未确定。
  • 成功:服务商确认款项。
  • 失败:被拒绝、被取消或被拦截。
  • 已过期:支付时限已过,没有结果。
  • 部分退款与全额退款:成功后退回部分或全部款项。

银行卡还可能有“已授权、未请款”的状态,之后还可能出现争议(拒付)。把允许的状态转换写进代码:已创建可以变为待处理;已创建或待处理可以变为成功、失败或已过期;成功可以变为部分退款或全额退款,部分退款之后还可以继续退款;任何状态都不会回到已创建或待处理。除此之外的变化,要么是 bug,要么需要人工复核。

在服务端确认,来源必须可验证

可信的来源有两个,稳健的集成会同时使用。

带签名的 Webhook。 发生事件时,服务商会调用您的接口;大多数服务商会用双方共享的密钥为每个请求签名,通常是对原始请求体计算 HMAC-SHA256,并常常带上时间戳。您的处理程序应当:

  1. 按收到时的原样读取原始请求体。先解析 JSON 再重新序列化,可能改变空白、转义或键的顺序,签名就对不上了。
  2. 自行计算 HMAC,并用恒定时间比较与请求头中的签名比对。普通的字符串比较在第一个不同的字符处就会停止,这个时间差可能泄露正确签名的信息。
  3. 拒绝超出短时间窗口的时间戳(常见做法是五分钟),让被截获的请求无法事后重放;时间窗口内的重放,则由按事件 ID 去重来拦截。
  4. 将金额、币种和订单号与您创建的订单核对。签名有效只能证明消息是谁发的,不能证明顾客为正确的订单付了正确的金额。金额以货币最小单位的整数存储,不要用浮点数。

服务商的 API。 服务器用您的密钥按 ID 查询这笔支付。这可以弥补迟到或丢失的 Webhook;有些团队干脆只把 Webhook 当作信号,收到后再去查询当前状态。

API 密钥和 Webhook 签名密钥只放在服务器上,不进应用安装包,也不进代码仓库,并且要能在不停机的情况下轮换。

幂等:同一事件来两次,什么都不会改变

大多数服务商按“至少一次”的方式投递 Webhook:您的接口超时或返回错误,事件就会重发,有时会重发多次。重复是常态,所以处理逻辑必须是幂等的。

  • 按事件 ID 去重。 已处理的事件 ID 存在唯一约束之下,重复投递不会改变任何东西。
  • 一个事务,一次更新。 在同一个数据库事务里记录事件 ID 并修改订单状态;任何一步失败都会一起回滚,重试时从干净的状态开始。更新语句要带条件(WHERE status = 'pending'),这样同时到达的 Webhook 和 API 查询不会把同一订单处理两次。
  • 创建支付和退款时使用幂等键。 如果服务商支持,就用您自己的支付尝试 ID 生成幂等键;超时后重试会拿到原来的结果,而不会重复扣款。如果不支持,先用唯一的参考号保存您自己的记录,重试前先按参考号查询。
  • 事件可能乱序。 投递顺序通常不受保证,成功事件可能晚于退款事件到达。按状态转换规则处理,而不是用最后到达的事件覆盖,拿不准时就查询当前状态。
  • 退避重试。 对超时、连接错误、429 和 5xx 响应进行重试,采用指数退避加随机抖动,并限制次数。参数校验类错误不要重试。
  • 超时意味着结果未知,而不是失败。 款项可能已经扣了,要通过查询来确认。
  • 定时处理过期。 定时任务找出超过时限仍在待处理的支付,先向服务商查询,再标记为已过期。过期之后才到的成功(银行转账确实会出现这种情况),按事先约定的规则转人工复核或退款。

Webhook 要快速响应:保存、提交、返回 2xx,发邮件、发货这类慢操作放进队列。处理程序太慢会导致超时,而超时会带来更多重复。

落到代码上

下面是一个用 TypeScript 写的最小处理程序,基于 Node.js 和 PostgreSQL。请求头名称、签名编码和被签名的字符串因服务商而异,但整体结构不变。

TypeScript
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。

上线前检查清单

  1. 订单只能通过已验证的 Webhook 或服务端 API 查询变为已支付。
  2. 基于原始请求体、以恒定时间比较验证签名;过期的时间戳一律拒绝。
  3. 金额、币种和订单号都与订单核对。
  4. 事件 ID 唯一;重复投递返回 2xx,且没有副作用。
  5. 事件记录与状态变更在同一事务中提交,更新语句带条件。
  6. 创建支付和退款都使用幂等键,或按自有参考号查询。
  7. 状态转换在代码中定义;迟到的事件不能让订单状态倒退。
  8. Webhook 接口在服务商的超时时间内响应;慢操作进队列。
  9. 对外调用设有超时,重试有上限,并采用退避与抖动。
  10. 待处理支付经状态查询后按计划过期;过期后才到的成功有明确的处理路径。
  11. 部分退款不会超过已扣款金额。
  12. 每天运行对账,每一项差异都有负责人。
  13. 保留原始 Webhook 和状态历史;日志中没有密钥或完整卡号。
  14. 告警覆盖验签失败、处理错误、卡住的支付和对账差异。

silvercloud 是一支外包开发团队。我们为合作企业在应用和网站中构建这一层,从结账、Webhook 到退款和对账,也按合作方的需求开发支付网关系统,完成后交付给对方团队运营。如果您正在规划支付集成,欢迎通过 silvercloud.city 发送需求简报。

发送支付集成需求简报