短剧系统支付配置教程

支付配置教程：支付宝 + PayPal

接着上一篇的OSS说支付。这套系统内置了支付宝手机网站支付和PayPal两条通道，全部在后台管理里配，不用改代码、不用重启服务，保存就生效。踩坑点集中在回调域名和支付宝的公钥模式上，照下面顺序来基本一遍过。

先配通用项

• 后台管理 → 设置 → 支付配置 → 「通用」，填「回调域名(公网)」，填的是后端API的公网地址，比如 https://api.你的域名。支付宝的异步通知地址和两家的支付完成跳转地址都是系统拿这个值自动拼出来的，你不用手填完整URL。留空会用当前请求域名，只有后端直接对外的部署才够用；本地联调填内网穿透地址。

支付宝部分

• 去支付宝开放平台创建应用，签约「手机网站支付」并把应用上线。代码走的是 alipay.trade.wap.pay，没签这个产品，用户点付款时会直接报错。

• 生成RSA2密钥对，加签方式一定要选公钥模式，不要用公钥证书模式。这套代码只加载支付宝公钥，证书模式那三个 .crt 文件是配不上的；如果应用已经开成证书模式，得回开放平台切回公钥模式。

• 后台「支付宝」标签填四项：AppID、应用私钥(RSA2)、支付宝公钥、生产环境开关。私钥直接粘贴平台给你的那一整串，PKCS1和PKCS8两种格式都能识别。

• 第三栏必须填支付宝公钥，不是你自己生成的那个应用公钥——这是最容易搞混的一处。填错的表现很有欺骗性：下单、跳收银台、付款全都正常，只有异步通知验签一直失败，订单永远停在待支付，钱到账了权益不发。

PayPal部分

• 去 developer.paypal.com 的 Apps & Credentials，先在Sandbox建应用拿Client ID和Secret联调，上线再换成Live的那一对。

• 在同一个应用里创建Webhook，URL填 https://你的回调域名/api/v1/payments/paypal/webhook，事件至少勾上 CHECKOUT.ORDER.APPROVED 和 PAYMENT.CAPTURE.COMPLETED（其他事件后端会直接忽略，不用多勾）。保存后把页面上的Webhook ID复制到后台。

• 后台「PayPal」标签填五项：Client ID、Secret、Webhook ID、生产环境开关、人民币兑美元汇率。汇率默认7.2，只接受1到20之间的值，填超范围会被忽略并回落到默认值。美元金额是「人民币价格÷汇率」实时算的，改汇率不影响已经生成的订单。

• Webhook ID别省。不填照样能支付，但用户在收银台付完直接关页面的那批订单就没人兜底结算了——钱到账、权益不发，这类客诉最难查。另外这里的验签走的是PayPal官方回传校验，所以开发者后台那个「模拟事件」按钮测不通，必须用真实沙箱交易联调。

验收和排错

• 前台的收银台只显示已配好的渠道：开关打开、并且关键凭证（支付宝的AppID、PayPal的Client ID）非空，渠道才会出现。配完记得回App或H5确认渠道列表已经出来了。

• 沙箱联调时把两个「生产环境」开关都关着，走的分别是支付宝沙箱和PayPal Sandbox，要用对应的沙箱买家账号付款。上线前逐个打开，别漏。

• 支付宝订单迟迟不变已支付，九成是回调不通或公钥填错。先确认 https://回调域名/api/v1/payments/alipay/notify 从公网能访问（宝塔的伪静态要把 /api/ 反代给后端进程），再核对支付宝公钥那一栏。

• 客户端还有两道兜底：App付完回来会主动查一次单，H5会在支付等待页轮询订单状态。所以偶发的通知延迟不会卡住用户，但如果通知长期不通，退款这类只能从异步通知进来的事件就彻底收不到了，必须查通。

• 私钥和Secret保存后会显示成 ********，表示库里已有。再次保存表单时不动这两栏就不会被覆盖，需要更换时直接填新值。

写到最后

支付这块是我验证得最仔细的地方，毕竟直接跟钱有关。让我比较放心的几个细节：金额和汇率一律以服务端为准，不采信客户端和通知里传回来的数；PayPal要等捕获状态真的变成COMPLETED才发权益，不会因为风控复审就提前放货；支付宝的退款通知也接住了，不会出现退了款钻石还留着的情况。这些都是自己写容易漏、漏了要真赔钱的地方。