PayPal 订单 COMPLETED、钱却没到账:capture 的 PENDING 与 21 天资金保留是两件事
现象
接 PayPal Orders v2 后,前端 onApprove 回调调后端 capture,接口返回 order.status = COMPLETED,订单随即被标记为已支付并发货。第二天财务对账,PayPal 余额里没有这笔钱,买家侧却已经扣款。后台交易显示「付款已收到,待处理」,客服答复是「新卖家资金保留 21 天」。
这类工单里混了四个不同层面的状态:
order.statuspurchase_units[].payments.captures[].statusstatus_details.reason- 账户级资金可用性(funds availability)
任何一层看错,都会得出错误结论。
第一层:order.status = COMPLETED 不代表收到钱
官方 order_status 定义写得很清楚:COMPLETED 表示 order 的 intent 已完成、payments 资源已创建,它可能是「已授权」「已 capture」「已被拒绝」三种情况之一,必须再读 purchase_units[].payments.captures[].status。
也就是说,capture 接口返回 201 和 order.status=COMPLETED,只能证明这次调用被受理,不能证明钱进了你的 PayPal 余额。
代码里第一件事:不要用 order.status 做发货判断。
type Capture struct {
ID string `json:"id"`
Status string `json:"status"`
StatusDetails struct {
Reason string `json:"reason"`
} `json:"status_details"`
Amount struct {
CurrencyCode string `json:"currency_code"`
Value string `json:"value"`
} `json:"amount"`
SellerProtection struct {
Status string `json:"status"`
} `json:"seller_protection"`
}
type Order struct {
ID string `json:"id"`
Status string `json:"status"`
PurchaseUnits []struct {
Payments struct {
Captures []Capture `json:"captures"`
} `json:"payments"`
} `json:"purchase_units"`
}
发货判定只看 captures,且要遍历:一次 order 可能有多个 purchase_unit。
第二层:capture 的六个状态,只有 COMPLETED 能发货
官方 capture_status 枚举:
COMPLETED:资金已计入收款方 PayPal 账户PENDING:资金尚未计入收款方账户,看status_detailsDECLINED:无法 captureFAILED:capture 过程出错PARTIALLY_REFUNDED:已部分退款REFUNDED:已全额或超额退款
注意 COMPLETED 的定义是「credited to the payee's PayPal account」,它说的是入账到 PayPal 余额,不是「可提现」。这点后面讲 21 天保留时会再回到。
PENDING 与 DECLINED 会带 status_details.reason。这个字段才是排查入口。
第三层:status_details.reason 怎么读
Payments v2 的枚举(Orders v2 文档里同一对象,字段一致):
| reason | 含义 | 处置 |
|---|---|---|
UNILATERAL | 收款方没有可用/未确认的 PayPal 账户(常见于 payee.merchant_id 填错、邮箱未确认) | 核对 merchant_id 与账户邮箱;这是配置问题,不是风控 |
PENDING_REVIEW | 人工审核中 | 等,通常 24 小时内出结果;不要重复 capture |
ECHECK | 买家用了 eCheck,尚未清算 | 等清算,通常几个工作日;不要发货 |
RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION | 收款账户没设置收款偏好(典型是币种与主币种不同) | 在账户里设置自动转换/接受,或手动接受该笔 |
VERIFICATION_REQUIRED | 收款账户未完成验证 | 完成账户验证 |
INTERNATIONAL_WITHDRAWAL | 跨境提现需在账户里接受或拒绝 | 登录账户操作 |
TRANSACTION_APPROVED_AWAITING_FUNDING | 买家需另行汇款(多见于手工 EFT) | 等资金到账,不能发货 |
BUYER_COMPLAINT | 买家已发起争议 | 转争议流程,别发货 |
CHARGEBACK | 发卡行已拒付 | 转争议流程 |
DECLINED_BY_RISK_FRAUD_FILTERS | 收款方设置的欺诈过滤器拦下 | 核对风控规则 |
OTHER | 无具体原因 | 去账户后台看,或联系 PayPal |
UNILATERAL 在沙箱里特别常见:payee 的 merchant_id 指向一个不存在的沙箱账户、或邮箱没确认。StackOverflow 上 2020 年那个 3441 浏览的案例就是 INR 收款 + 未确认沙箱邮箱,capture 返回 COMPLETED、capture.status 为 PENDING、reason=UNILATERAL。
处理原则:PENDING 不进「已支付」,也不进「失败」,单独建一张待定表,记录 capture_id、reason、首次出现时间,挂定时查单。
第四层:capture = COMPLETED,钱仍然可能被扣 21 天
这是最容易误判的一层,也是标题里的场景。
PayPal 对新卖家、长期未销售、争议率偏高、销售模式突变、高风险品类(门票、礼品卡、消费电子、旅游套餐)会做资金保留(payment hold)。官方口径是通常最多 21 天,满足条件可提前释放:上传可跟踪的物流单号、买家确认收货、或时间到期。
关键点:这个 hold 不在 capture.status 里。capture 仍是 COMPLETED,API 没有任何字段告诉你「这笔钱现在不可用」。只能从账户后台的余额明细、PayPal 发的「An important message about your PayPal balance」邮件、或账户概览的提醒里看到。
所以对系统的正确建模是:
- 订单维度:
capture.status = COMPLETED就可以发货。 - 资金维度:另有一张「可用余额」视图,来自 settlement / 报表,而不是 capture 接口。
- 不要把 21 天 hold 当支付失败,也不要因此重复 capture 或退款重下。
账户级还有 reserve(滚动保留、最低保留、jumpstart reserve),同理不影响单笔订单判定,只影响现金流预测。滚动保留的典型形态是每笔扣 5%、保留 60 天。
Webhook:event_type 与 resource.status 会对不上
实际踩过的坑。有人收到 PAYMENT.CAPTURE.COMPLETED,打开 resource 却发现 status=PENDING、reason=PENDING_REVIEW(StackOverflow 72444320,2022)。
原因不复杂:事件名描述的是「状态发生了变化」,resource 是你收到通知那一刻的快照,两者在审核/异步场景下不一定同步。PayPal 自己的 Payment Lifecycle 文档也要求:Order 到 COMPLETED 后,capture 生命周期才开始,必须单独跟踪 capture 状态。
所以 webhook 处理要遵守三条:
- 不要用
event_type直接映射业务状态。以resource.status为准,event_type只用来路由。 - 幂等键用
resource.id(capture id),不要用 order id,也不要用 event id 做去重主键。PENDING → COMPLETED是同一个 capture id 的状态推进,用 order id 会让第二条覆盖不了第一条,用 event id 会重复插入。 - 状态只允许前进,不允许回退。
COMPLETED之后再来PENDING视为乱序,直接丢弃并记日志。
func applyCapture(tx *sql.Tx, c Capture) error {
switch c.Status {
case "COMPLETED":
// 条件更新,防止 DECLINED/REFUNDED 被覆盖
_, err := tx.Exec(`UPDATE payments SET status='paid', paid_at=NOW()
WHERE capture_id=? AND status IN ('pending','created')`, c.ID)
return err
case "PENDING":
_, err := tx.Exec(`INSERT INTO payments (capture_id, status, pending_reason, created_at)
VALUES (?, 'pending', ?, NOW())
ON DUPLICATE KEY UPDATE pending_reason=VALUES(pending_reason)`, c.ID, c.StatusDetails.Reason)
return err
case "DECLINED", "FAILED":
_, err := tx.Exec(`UPDATE payments SET status='failed'
WHERE capture_id=? AND status IN ('pending','created')`, c.ID)
return err
case "REFUNDED", "PARTIALLY_REFUNDED":
_, err := tx.Exec(`UPDATE payments SET status='refunded'
WHERE capture_id=?`, c.ID)
return err
}
return nil
}
Webhook 事件名(Payments v2):PAYMENT.CAPTURE.PENDING / COMPLETED / DECLINED / REFUNDED / REVERSED,退款侧 PAYMENT.REFUND.PENDING / FAILED。注意 DECLINED 和 DENIED 两个词在不同版本文档里都出现过,订阅时以控制台事件名为准。
退款侧:PAYMENT.REFUND.PENDING 不是失败
eCheck 支付的退款会先 PENDING,要等买家银行清算,可能几天。收到 PAYMENT.REFUND.PENDING 时把退款单标为处理中,别标失败,也别重提。只有 PAYMENT.REFUND.FAILED 才是失败。
退款后 capture.status 会变 REFUNDED 或 PARTIALLY_REFUNDED,但这两者与「买家已收到钱」不是同一件事,退款到账时间取决于资金来源。
授权与 capture 的时间窗
如果用的是 intent=AUTHORIZE 再 capture:官方集成文档写 authorization 有效期 29 天,而 PAYMENT.AUTHORIZATION.VOIDED 的事件说明写的是 30 天有效期到期自动 void。两处口径不一致,按 29 天做业务倒计时更安全(更早 capture)。未在沙箱逐日验证到期边界。
上线前要落地的四件事
- 发货判定只看
capture.status == COMPLETED,永远不看order.status。 PENDING单独建模,带reason与首次时间,定时任务按capture_id查GET /v2/payments/captures/{capture_id}收敛状态。- 资金可用性单独出报表,来自 settlement 报表,不从 capture 接口推。
- webhook 幂等按 capture id,状态只前进。
边界与未实测
- 21 天 hold、
PENDING_REVIEW在沙箱基本复现不出来;相关结论来自 PayPal 官方商户文档与客服口径,未做资金实测。 - 29/30 天授权有效期两处文档不一致,按 29 天保守处理。
- 币种限制(如 INR 只能由印度买家支付)来自社区答复,未逐一验证。
- 示例 Go 代码未在生产环境跑过完整链路。
文档链接:
- capture_status 枚举:https://developer.paypal.com/api/orders/v2/definitions/capture_status
- order_status:https://developer.paypal.com/api/orders/v2/definitions/order_status
- seller_protection:https://developer.paypal.com/api/orders/v2/definitions/seller_protection
- webhook 事件名:https://developer.paypal.com/api/rest/webhooks/event-names
- 资金保留说明:https://www.paypal.com/us/brc/article/funds-availability
- 支付生命周期:https://developer.paypal.com/platforms/checkout/apm/reference/lifecycle