PayPal 是很多跨境 SaaS、独立站、工具产品会考虑的支付方式。它覆盖范围广用户熟悉度高尤其在国际市场里PayPal 仍然是很重要的付款选项。但 PayPal 接入和 Stripe 的思路不完全一样。很多坑不是出在“能不能弹出 PayPal 按钮”而是出在环境、账号、订单捕获、Webhook、订阅状态和生产切换上。本文基于 PayPal 官方文档整理Get started with PayPal REST APIsPayPal sandbox testing guideSubscriptionsIntegrate SubscriptionsSubscriptions webhooksSubscribe to checkout webhooksMove your app to production坑一沙盒账号和生产账号混用PayPal 有 sandbox 和 live 两套环境。沙盒用来模拟真实付款不会触碰真实资金生产环境才是真实交易。PayPal 官方 sandbox 文档说明sandbox 是一个独立测试环境可以用虚拟账号模拟真实交易。常见错误是前端用了 sandbox client id后端却调用 live endpoint或者数据库里保存了 sandbox 订单 ID生产环境又拿来校验或者测试买家账号和商家账号混在一起。你要明确区分sandbox client id sandbox client secret sandbox business account sandbox personal buyer account sandbox API endpoint live client id live client secret live merchant account live API endpoint支付系统里环境混用是最难排查的坑之一。坑二只拿 client id不理解 access tokenPayPal REST API 使用 OAuth 2.0 access token。PayPal 官方 REST 文档说明调用 API 时需要用 client id 和 client secret 换取 access token。client id 可以用于按钮和部分前端 SDK 场景但 client secret 必须保存在服务端。不要把 client secret 放到前端。后端需要用它换 access token再调用 PayPal API。一个基本关系是client id client secret - access token access token - 调用 PayPal REST API如果你只理解前端按钮不理解后端 token就很容易在订单确认、订阅查询和 Webhook 校验时卡住。坑三以为用户批准就等于付款完成PayPal Checkout 里用户批准付款不等于你已经收到了钱。订单通常需要经历创建、用户批准、捕获支付等步骤。真正的履约应该在支付 capture 完成之后进行。PayPal Checkout Webhook 文档也提醒PAYMENT.CAPTURE.PENDING代表支付完成仍在等待不应在支付完成前履约PAYMENT.CAPTURE.COMPLETED才是可以履约的重要事件。所以不要在用户点击 PayPal 按钮后立刻开通权益也不要只因为前端返回成功就发货。正确做法是后端确认订单 capture 完成或通过 Webhook 收到完成事件后再更新本地订单状态。坑四不处理 WebhookPayPal Webhook 是支付状态同步的关键。PayPal 官方 Webhooks 文档说明Webhook 是 PayPal 在事件发生时向你的服务端发送的 HTTPS POST。订阅、退款、支付完成、支付失败、订单状态变化都可能通过 Webhook 通知。如果你不处理 Webhook就很容易遇到这些问题用户付款成功但本地没有开通 用户退款了但系统仍然有权限 订阅付款失败但本地仍然显示有效 订阅取消了但系统没有同步 支付 pending 时提前履约PayPal 支付集成必须有 Webhook 处理链路。坑五不验证 WebhookWebhook 来自外部网络不能直接相信请求内容。PayPal Webhooks 文档提到可以把消息、webhook id 和 header 信息提交给 PayPal 的 verify signature endpoint 进行签名验证。也就是说你收到 Webhook 后要确认它确实来自 PayPal再处理业务。基本流程应该是接收 Webhook 保存原始事件 验证签名 按 event id 去重 分发事件处理 更新本地状态 记录日志不要把 Webhook 当普通公开接口处理。坑六订阅只处理创建不处理整个生命周期PayPal 订阅不是创建成功就结束。PayPal 订阅文档里列出了很多订阅相关 Webhook例如BILLING.SUBSCRIPTION.CREATED BILLING.SUBSCRIPTION.ACTIVATED BILLING.SUBSCRIPTION.UPDATED BILLING.SUBSCRIPTION.CANCELLED BILLING.SUBSCRIPTION.SUSPENDED BILLING.SUBSCRIPTION.EXPIRED BILLING.SUBSCRIPTION.PAYMENT.FAILED PAYMENT.SALE.COMPLETED如果你只处理订阅创建就会错过续费、失败、取消、暂停和过期。本地数据库至少要保存paypal_subscription_id paypal_plan_id subscription_status current_period last_payment_status cancelled_at用户权限应该根据本地同步后的订阅状态判断而不是只看第一次创建。坑七产品和计划没有提前规划PayPal Subscriptions 通常会涉及 Product 和 Plan。官方订阅文档说明订阅流程一般包括创建 product、创建 plan、用 JavaScript SDK 展示 PayPal 按钮、买家同意并订阅。如果你产品里有多个套餐、月付年付、试用、升级降级就要提前规划 PayPal plan 和你本地 plan 的映射。不要把 PayPal plan id 散落在代码里。建议保存到配置或数据库local_plan pro_monthly paypal_plan_id P-xxx currency USD interval month这样后面改价格、加套餐、切换环境时更安全。坑八没有处理 pending、denied 和失败状态支付不是只有成功和失败两种状态。PayPal Webhook 里可能出现 pending、denied、reversed、failed 等事件。尤其在跨境支付、不同支付方式、风控审核场景下状态可能不会立即完成。不要把所有非成功状态都简单当失败也不要在 pending 时提前开通长期权益。比较稳妥的策略是COMPLETED开通或延长权益 PENDING标记等待不开通长期权益 DENIED / FAILED提示用户重试或更换方式 REVERSED / REFUNDED回收或调整权益状态机越清楚支付问题越少。坑九上线时只换了部分配置PayPal 官方生产环境文档提醒上线时要获取 live credentials并把 API endpoint 从 sandbox 改为 live。常见上线错误是只换了前端 SDK client id没有换后端 secret或者换了 API endpoint但 webhook URL 仍然指向测试环境或者 live app 没有启用对应能力。上线清单至少包括前端 SDK client id 后端 client secret API base URL Webhook URL Webhook 订阅事件 Product / Plan id 数据库环境配置 测试账号和真实账号区分PayPal 上线不是“把 sandbox 改成 live”这么简单。坑十测试太少PayPal 官方 sandbox 文档建议用 sandbox 测试和调试流程。你至少要测试普通一次性付款成功 用户取消付款 支付 pending 支付 denied 订阅创建 订阅续费 订阅付款失败 订阅取消 退款 Webhook 重复发送 Webhook 签名失败如果只测试“按钮弹出”和“付款成功”上线后一定会遇到意外状态。写在最后PayPal 的难点不是把按钮放到页面上而是把支付生命周期和你本地业务状态同步好。一个可靠的 PayPal 接入要重点处理sandbox/live 分离、服务端 access token、capture 完成后履约、Webhook 验签、订阅生命周期、pending 状态、生产切换和充分测试。下一篇我们继续聊基础能力选型邮件发送方案对比。原文链接PayPal 接入避坑 | Harries Blog™