配置PayPal接入

06 商品与交易 / 06.02 支付接入

准备 PayPal 应用

瓜奇使用 PayPal REST 应用收款。先准备相应环境的 Client ID、Secret，以及接收支付通知所需的 Webhook ID。账户收款资格和可用币种，以实际账户为准。

在 PayPal Developer 的 Apps & Credentials 中选择或创建 REST 应用。测试使用 Sandbox，正式收款使用 Live，两套凭据不能混用。相关说明见PayPal REST 入门。

填写瓜奇设置

使用能保存瓜奇设置的后台账号，进入「支付」→「PayPal」，按以下顺序配置。

1. 打开「启用此支付方式」。
2. 填写支付名称、说明和图标，并在「支持的货币」中选择实际要收款的币种。
3. 填写同一 REST 应用、同一环境下的「Client ID」和「Secret」。
4. 设置「是否启用沙盒模式」：沙盒凭据配合开启状态，正式凭据配合关闭状态。
5. 将「前台支付形式」设为「跳转收银台」。当前流程返回收银台跳转信息，选择扫码不会把它变成二维码支付。

配置 Webhook ID

Webhook 是 PayPal 主动向网站发送支付结果的通知。为对应应用和环境配置目标前端的 /api/callback 端点，至少订阅 CHECKOUT.ORDER.APPROVED 和 PAYMENT.CAPTURE.COMPLETED。

将该端点的 Webhook ID 填入瓜奇「Webhook ID」。它是通知验签所需的标识，不是 Client ID，也不是 Secret。

当前游客付款必须配置 Webhook ID；缺少时会提示 PayPal Webhook ID is required for guest payment。即使填好了此项，游客仍需满足具体业务的购买条件。

保存并测试完整流程

1. 保存设置，从买家实际使用的前端发起沙盒订单，确认币种、金额和 PayPal 入口正确。
2. 检查能否打开 PayPal 收银台并完成测试付款。
3. 检查浏览器能否返回网站，同时确认通知端点能够接收并处理 PayPal 事件。
4. 核对瓜奇订单支付状态，再检查购买的内容或权益是否可用。计划支持游客时，还要单独测试游客流程。

浏览器回跳使用目标前端的 /notify?gqPayment=paypal，代码会附带订单号。回跳与服务器通知作用不同，看到返回页面不能代替订单状态检查。

切换正式环境

关闭沙盒模式，换成正式应用的 Client ID、Secret 和对应通知端点的 Webhook ID。随后重新验证正式付款、订单确认和业务交付，不能只凭沙盒成功判断正式配置已完成。

当前代码使用沙盒接口 api-m.sandbox.paypal.com 和正式接口 api-m.paypal.com。出现认证错误时，先核对凭据与沙盒开关，不要把正式域名改成 api-m.live.paypal.com。

如果入口不显示，检查渠道是否启用、当前币种是否支持，以及当前身份能否购买。若已付款但订单未更新，继续检查通知端点和 Webhook ID 是否属于同一环境。