PayPal 支付停在 APPROVED:capture 和回调幂等

2026-11-19 后端开发 有希 47 次浏览

买家在 PayPal 页面点了同意,回到站点订单却一直是“待支付”;后台看到的 PayPal 状态是 APPROVED,不是 COMPLETED。这不是回调丢了,而是 APPROVED 只代表买家授权,钱还没有扣。另一些订单则是扣了钱、回调又重复到达,业务侧重复发货。本文用 PayPal Orders v2 的完整流程,说明 capture 为什么会被 415 拦住、超时后怎么查,以及 webhook 和主动查询如何做到只处理一次。

先给结论

PayPal 的订单状态机是 CREATED → APPROVED → COMPLETED。APPROVED 表示买家同意付款,但商户还没有发起 capture;只有 capture 成功、状态变成 COMPLETED,钱才真正扣掉。

两个必须做对的地方:

  1. capture 请求必须带 JSON 请求体。空 body 即使带了路径,也可能返回 415 Unsupported Media Type,订单就停在 APPROVED。
  2. capture 可能超时、webhook 可能重复。业务侧要用条件更新或唯一约束保证幂等,不能靠“回调只来一次”。

现象:买家说付了,订单还是待支付

现象实际状态常见原因
买家同意后回到站点,订单未支付APPROVED没有调用 capture,或 capture 失败
capture 接口返回 415APPROVED请求没有 JSON body / Content-Type
capture 超时,重试报已扣款COMPLETED 或处理中第一次其实成功,超时后盲目重试
钱扣了,订单被处理两次COMPLETEDwebhook 与主动查询同时触发,业务不幂等
回调一直失败COMPLETED验签或处理返回 5xx,PayPal 持续重试
金额对不上COMPLETED只比了本地价格,没比 capture 的实际金额和币种

APPROVED 不是“支付成功”的同义词。把它当成功,就会出现“买家已付款、站点没发货”或“站点已发货、其实没扣款”两种相反的事故。

创建订单:把业务单号带进去

创建订单时用 intent: CAPTURE,并把本地订单号写进 custom_id 或 reference_id,回调才能找回业务单:

curl -s https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [{
      "reference_id": "default",
      "custom_id": "ORDER20261119001",
      "amount": { "currency_code": "USD", "value": "10.00" }
    }],
    "application_context": {
      "return_url": "https://example.com/pay/return",
      "cancel_url": "https://example.com/pay/cancel",
      "user_action": "PAY_NOW",
      "shipping_preference": "NO_SHIPPING"
    }
  }'

返回里 status 是 CREATED,links 里有一条 rel: approve 的地址。把买家跳转到这个地址,买家登录并同意后,PayPal 会把订单改成 APPROVED,再跳回 return_url。

custom_id 最大 127 字符,适合放业务单号;reference_id 用于区分多个 purchase unit。两者都不是支付凭证,真正的凭证是 capture 返回的 capture id。

为什么 capture 会 415

capture 的端点:

POST /v2/checkout/orders/{order_id}/capture

PayPal 要求请求体是 JSON,哪怕没有额外参数也要发一个空对象:

curl -s -X POST \
  https://api-m.sandbox.paypal.com/v2/checkout/orders/$ORDER_ID/capture \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

如果代码里用 http.NewRequest 传了 nil body,又没有正确设置 Content-Type,服务端可能直接返回 415,请求根本没有进入支付逻辑。修复通常很小:

body := strings.NewReader("{}")
req, err := http.NewRequest(http.MethodPost, captureURL, body)
if err != nil {
    return err
}
req.Header.Set("Content-Type", "application/json")

关键不是“随便发点字节”,而是让 HTTP 请求在头和体上都符合 JSON 语义。很多 415 不是 PayPal 的配置问题,而是客户端把空 body 当成了合法 JSON 请求。

状态机:APPROVED 之后还要做什么

状态含义能否发货
CREATED订单已创建,买家未同意否
APPROVED买家已同意,尚未扣款否
COMPLETEDcapture 成功,已扣款是
VOIDED订单已取消否
PAYER_ACTION_REQUIRED需要买家额外操作(如 3DS)否

CHECKOUT.ORDER.APPROVED 这个 webhook 只说明买家同意了,不说明扣款成功。真正的付款信号是:

  • PAYMENT.CAPTURE.COMPLETED
  • CHECKOUT.ORDER.COMPLETED

失败信号是 PAYMENT.CAPTURE.DENIED;取消信号是 CHECKOUT.ORDER.VOIDED。收到 APPROVED 就发货,是最常见的误判。

capture 成功后,响应里的关键字段是:

{
  "id": "ORDER_ID",
  "status": "COMPLETED",
  "purchase_units": [{
    "payments": {
      "captures": [{
        "id": "CAPTURE_ID",
        "status": "COMPLETED",
        "amount": { "currency_code": "USD", "value": "10.00" }
      }]
    }
  }]
}

业务侧至少要存 CAPTURE_ID,并按 captures[0].amount 核对金额和币种。只比本地订单价格,无法发现币种错配或部分 capture。

超时:不要立刻重试,先查订单

capture 可能因为网络、PayPal 抖动或客户端超时被中断。此时请求可能已经成功,只是响应没回来。直接重试会得到 ORDER_ALREADY_CAPTURED,更糟的是如果业务逻辑把“异常”当失败,会出现钱扣了、订单没更新。

正确处理顺序:

capture 超时
  → GET /v2/checkout/orders/{id}
  → status = COMPLETED:取 captures[0],标记成功
  → status = APPROVED:带同一个 PayPal-Request-Id 重试 capture
  → status = CREATED:买家未完成,回到支付页

PayPal-Request-Id 是 PayPal 的幂等键。同一个逻辑 capture 的重试要复用同一个值,不要每次生成新 UUID。这样即使第一次已经成功,重复请求也不会产生第二笔扣款。

如果订单状态是 PAYER_ACTION_REQUIRED,说明需要 3DS 等额外验证,响应里会有 payer-action 链接,必须把买家送回 PayPal 完成验证,不能直接当失败。

回调幂等:webhook 和主动查询只能算一次

PayPal webhook 是至少一次投递,可能重复、乱序,也可能延迟。同一笔订单还可能同时被 webhook 和定时主动查询命中。业务处理必须满足:无论调用多少次,结果一致,副作用只发生一次。

数据库层用条件更新,而不是先查再改:

UPDATE pay_order
SET status = 'success',
    transaction_id = ?,
    paid_at = NOW()
WHERE out_trade_no = ?
  AND status = 'waiting';

检查受影响行数:

  • 1 行:本次完成状态迁移,可以发货。
  • 0 行:已经成功、状态不允许迁移,或单号不存在。不要再发货。

再给 transaction_id 或 out_trade_no 加唯一约束,作为最后一道防线。条件更新解决并发,唯一约束解决重复插入,两者不能互相替代。

验签要用原始请求体

PayPal webhook 验签调用:

POST /v1/notify-webhook-signatures/verify

请求里带 transmission_id、transmission_time、cert_url、auth_algo、transmission_sig、webhook_id 和完整的 webhook_event。签名覆盖的是原始请求体,所以中间件必须先读原始字节并验签,再把同一份字节交给 JSON 解析。

如果框架先把 body 解析成结构体、再重新序列化去验签,字段顺序和空白可能变化,验签就会失败。失败时返回 5xx,让 PayPal 按策略重试;处理成功后再返回 2xx。不要对验签失败的请求返回 200,否则事件会永久丢失。

事件本身也要去重

条件更新能保证业务状态只迁移一次,但重复事件仍会反复调用处理逻辑。更稳的做法是记录 event.id,处理前先查是否见过;或者让处理函数本身完全幂等。两者选其一,不要依赖“PayPal 不会重复发”。

验证:沙箱里走一遍完整状态

步骤操作期望
1创建订单status = CREATED,返回 approve 链接
2买家同意status = APPROVED,本地仍未支付
3不带 body 调 capture返回 415,订单仍 APPROVED
4带 {} 和 JSON 头调 capturestatus = COMPLETED,拿到 capture id
5重复投递 PAYMENT.CAPTURE.COMPLETED业务只处理一次,订单不重复发货
6capture 超时后先查订单已成功则直接取 capture,不重复扣款
7修改 capture 金额再回调金额核对失败,拒绝发货并告警

第 3 步和第 5 步是重点:一个验证 415 的根因,一个验证幂等不是靠运气。只测“正常支付一次”无法发现这两类问题。

边界与坑

APPROVED 会过期。 订单有有效期,买家同意后长时间不 capture,订单可能失效,需要重新创建。不要把 APPROVED 当成可无限期补扣的凭证。

webhook 不保证顺序。 APPROVED 可能在 COMPLETED 之后到达。处理逻辑要按状态机判断,不能按事件到达顺序覆盖状态。

金额核对要用 capture 的实际值。 下单时的金额只是快照;capture 响应里的 amount 和 currency_code 才是实际扣款。两者不一致时拒绝发货并告警。

3DS/SCA 不是异常。 需要额外验证时,订单会进入 PAYER_ACTION_REQUIRED,必须让买家完成验证,而不是标记失败。

超时时间不要设得太短。 capture 是同步扣款,网络慢时 15 秒可能不够;超时后必须查订单,不能直接重试。

沙箱和正式环境要分开。 两套 base URL、client id、secret 和 webhook id 都不同。混用会出现“沙箱能过、正式 401”的问题。

相关工具

调试 PayPal 请求时,可以用 curl 命令生成工具 拼出带认证头和 JSON body 的 capture 请求;把请求转成代码时用 curl 转代码工具 对照生成结果。更多支付对接和回调排错记录放在 技术笔记。

FAQ

PayPal 显示 APPROVED 是付款成功了吗?

不是。APPROVED 只代表买家同意付款,商户还没有 capture。只有 capture 成功、订单变成 COMPLETED,钱才真正扣掉。

capture 为什么返回 415?

通常是请求没有 JSON body 或 Content-Type 不正确。即使没有额外参数,也要发送 {} 并设置 Content-Type: application/json。

capture 超时后能直接重试吗?

不要直接重试。先查询订单状态:已 COMPLETED 就取 capture id 标记成功;仍 APPROVED 才带同一个 PayPal-Request-Id 重试;CREATED 说明买家没完成。

webhook 重复到达怎么办?

用条件更新或唯一约束保证业务只迁移一次,并记录 event.id 去重。验签用原始请求体,处理失败返回 5xx 让 PayPal 重试。

PayPal 支付的关键不是“调通一次”,而是把 APPROVED 和 COMPLETED 分开、把超时和重复回调当成常态。状态机加幂等更新,才能保证钱和订单只对一次。

评论

登录后即可参与评论

还没有评论,来说两句吧

相关文章