PayPal 支付停在 APPROVED:capture 和回调幂等
买家在 PayPal 页面点了同意,回到站点订单却一直是“待支付”;后台看到的 PayPal 状态是 APPROVED,不是 COMPLETED。这不是回调丢了,而是 APPROVED 只代表买家授权,钱还没有扣。另一些订单则是扣了钱、回调又重复到达,业务侧重复发货。本文用 PayPal Orders v2 的完整流程,说明 capture 为什么会被 415 拦住、超时后怎么查,以及 webhook 和主动查询如何做到只处理一次。
先给结论
PayPal 的订单状态机是 CREATED → APPROVED → COMPLETED。APPROVED 表示买家同意付款,但商户还没有发起 capture;只有 capture 成功、状态变成 COMPLETED,钱才真正扣掉。
两个必须做对的地方:
- capture 请求必须带 JSON 请求体。空 body 即使带了路径,也可能返回
415 Unsupported Media Type,订单就停在APPROVED。 - capture 可能超时、webhook 可能重复。业务侧要用条件更新或唯一约束保证幂等,不能靠“回调只来一次”。
现象:买家说付了,订单还是待支付
| 现象 | 实际状态 | 常见原因 |
|---|---|---|
| 买家同意后回到站点,订单未支付 | APPROVED | 没有调用 capture,或 capture 失败 |
| capture 接口返回 415 | APPROVED | 请求没有 JSON body / Content-Type |
| capture 超时,重试报已扣款 | COMPLETED 或处理中 | 第一次其实成功,超时后盲目重试 |
| 钱扣了,订单被处理两次 | COMPLETED | webhook 与主动查询同时触发,业务不幂等 |
| 回调一直失败 | 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 | 买家已同意,尚未扣款 | 否 |
COMPLETED | capture 成功,已扣款 | 是 |
VOIDED | 订单已取消 | 否 |
PAYER_ACTION_REQUIRED | 需要买家额外操作(如 3DS) | 否 |
CHECKOUT.ORDER.APPROVED 这个 webhook 只说明买家同意了,不说明扣款成功。真正的付款信号是:
PAYMENT.CAPTURE.COMPLETEDCHECKOUT.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 头调 capture | status = COMPLETED,拿到 capture id |
| 5 | 重复投递 PAYMENT.CAPTURE.COMPLETED | 业务只处理一次,订单不重复发货 |
| 6 | capture 超时后先查订单 | 已成功则直接取 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 分开、把超时和重复回调当成常态。状态机加幂等更新,才能保证钱和订单只对一次。
Comments
No comments yet — be the first to say something