代码 PayPal 订单 COMPLETED、钱却没到账:capture 的 PENDING 与 21 天资金保留是两件事

2026-11-21 09:02:22

PayPal 订单 COMPLETED、钱却没到账:capture 的 PENDING 与 21 天资金保留是两件事

现象

接 PayPal Orders v2 后,前端 onApprove 回调调后端 capture,接口返回 order.status = COMPLETED,订单随即被标记为已支付并发货。第二天财务对账,PayPal 余额里没有这笔钱,买家侧却已经扣款。后台交易显示「付款已收到,待处理」,客服答复是「新卖家资金保留 21 天」。

这类工单里混了四个不同层面的状态:

  • order.status
  • purchase_units[].payments.captures[].status
  • status_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_details
  • DECLINED:无法 capture
  • FAILED: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 处理要遵守三条:

  1. 不要用 event_type 直接映射业务状态。以 resource.status 为准,event_type 只用来路由。
  2. 幂等键用 resource.id(capture id),不要用 order id,也不要用 event id 做去重主键。PENDING → COMPLETED 是同一个 capture id 的状态推进,用 order id 会让第二条覆盖不了第一条,用 event id 会重复插入。
  3. 状态只允许前进,不允许回退。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)。未在沙箱逐日验证到期边界。

上线前要落地的四件事

  1. 发货判定只看 capture.status == COMPLETED,永远不看 order.status。
  2. PENDING 单独建模,带 reason 与首次时间,定时任务按 capture_id 查 GET /v2/payments/captures/{capture_id} 收敛状态。
  3. 资金可用性单独出报表,来自 settlement 报表,不从 capture 接口推。
  4. 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

推荐文章

程序员茄子在线接单