PayPal

管理后台位置： Finance › Payment channels › PayPal (/payments/paypal)。开关和费率位于 Finance › Payment channels › Fees & limits (/payments/fees)。

功能说明

允许客户使用其 PayPal 余额、银行账户或保存在 PayPal 的银行卡为其 USD 钱包充值。客户还可以让 NexCMP 记住其 PayPal 账户以便进行 automatic top-up。对于偏好 PayPal 的客户，可将其与 Stripe 搭配使用。

前提条件

项目	要求
PayPal 账户	能够接收 USD 的 PayPal 企业 (Business) 账户。
REST 应用	PayPal 开发者后台（Apps & Credentials）中的一个 REST 应用，提供 Client ID 和 Client secret。使用 Sandbox 标签页进行测试，使用 Live 进行生产。
网络	可从互联网访问的 HTTPS（PayPal 会调用 Webhook）以及到 api-m.paypal.com（生产）或 api-m.sandbox.paypal.com（沙箱）443 端口的出站访问权限。
权限	REST 应用需要具备退款和 Webhook 功能。Check 对话框会显示是否同时具备这两个权限域。
依赖项	无。

准备基础设施

1. 使用您的企业账户登录 developer.paypal.com 并打开 Apps & Credentials。
2. 选择 Sandbox（测试）或 Live，然后点击 Create App。将其命名为例如 "NexCMP"。
3. 复制该应用的 Client ID 和 Secret。
4. 如需测试，请使用 Testing Tools › Sandbox Accounts 查找或创建一个个人 (Personal)（买家）沙箱账户。
5. 您无需自行创建Webhook；NexCMP会通过Create webhook按钮为您创建。

在NexCMP中连接

1. 打开Finance › Payment channels › PayPal（/payments/paypal）。
2. 在API keys中，选择Mode：live（真实资金，api-m.paypal.com）或sandbox（api-m.sandbox.paypal.com）。
3. 粘贴Client ID（至少20个字符）和Client secret。
4. 点击Check。它会测试您输入的凭据（无需保存）并报告连接状态、App ID、模式、是否具备退款和Webhook权限范围以及令牌的有效期。
5. 点击Save。
6. 在 Webhook 卡片中确认 URL 为 https://<your-domain>/v1/billing/paypal/webhook（必须是 https），然后点击 Create webhook 并确认。NexCMP 会请求 PayPal 创建或更新包含 11 个事件的 Webhook，并存储返回的 Webhook ID。该按钮使用已保存的密钥——如果刚修改过，请先保存。
7. 再次点击Check：Webhook行应显示“exists, 11 events”。
8. 打开Fees & limits，启用PayPal，将PayPal fee %（默认4.4）和PayPal fixed fee (cents)（默认30）设置为您的费率，然后点击Save channels & fees。

Webhook事件

NexCMP会注册这11个事件：CHECKOUT.ORDER.APPROVED、PAYMENT.CAPTURE.COMPLETED、PAYMENT.CAPTURE.PENDING、PAYMENT.CAPTURE.DECLINED、PAYMENT.CAPTURE.REFUNDED、PAYMENT.CAPTURE.REVERSED、CUSTOMER.DISPUTE.CREATED、CUSTOMER.DISPUTE.UPDATED、CUSTOMER.DISPUTE.RESOLVED、RISK.DISPUTE.CREATED、CHECKOUT.PAYMENT-APPROVAL.REVERSED。

每个Webhook都通过调用PayPal的签名验证API进行验证，存储一次并进行幂等处理。NexCMP绝不信任Webhook正文中的金额：在入账捕获之前，它会从PayPal获取该捕获。

验证

1. 将Mode保持为sandbox。在门户中打开Billing › Deposit，选择PayPal，点击Continue on PayPal（或PayPal按钮），并使用沙盒买家账户登录。
2. 批准付款。您返回门户，余额增加，付款将显示在Finance › Billing › Top-ups下，状态为Completed。
3. 打开Payment channels › Gateway events › PayPal & USDT：将列出PAYMENT.CAPTURE.COMPLETED事件。
4. 一切正常后，将Mode切换为live，输入生产凭据，点击Save，然后再次点击Create webhook（沙盒和生产Webhook是分开的）。

限制与注意事项

• 付款如何完成。 订单以USD创建；客户批准后，服务器会捕获它（幂等请求ID）并为钱包准确入账一次。如果客户关闭浏览器，Webhook和每10分钟运行一次的对账作业将作为安全网。
• 待处理和放弃的订单。 订单最多可保持打开12小时。一个客户最多可有5个待处理的订单（服务器响应too_many_pending，HTTP 429）。24小时后仍未捕获的订单将被标记为失败。
• 未配置Webhook。 在保存Webhook ID之前，面板对每个PayPal Webhook都响应HTTP 503。通过门户和10分钟对账进行的捕获仍会记入钱包，但PayPal通过Webhook报告的任何内容（争议、撤销、延迟捕获）都不会应用——请点击Create webhook。
• 已保存的PayPal账户。 当客户选择保存PayPal（或完成第一次充值，这会开启automatic top-up）时，PayPal会将支付令牌存储在其金库中。NexCMP只保留一个标识符和PayPal电子邮箱。请参见Saved payment methods。
• 退款和争议的处理方式与Stripe类似：退款请求在Finance › Payouts › Card refunds下审批；争议会冻结客户的账户并暂停其预付费服务，直到您解决争议。
• 费用。 PayPal的费用不会被读回；您配置的百分比和固定费用决定了客户看到的内容以及入账的金额。实际费率取决于您的国家/地区（表单提示越南为4.4%，美国为3.49%）。

故障排查

症状	原因	解决办法
"客户端 ID 太短"	粘贴的字符少于20个	复制完整的Client ID。
Webhook URL必须使用https	URL输入时带了http://	使用您的公开 https:// 域名。
检查报告连接错误	模式错误（沙盒中使用了正式密钥或相反）、密钥错误、无出站访问	将Mode与密钥类型匹配；从服务器测试curl -I https://api-m.paypal.com。
退款/webhook权限显示“no”	REST应用缺少相应功能	在PayPal Developer Dashboard的应用上启用这些功能。
横幅提示“PayPal key set, NO webhook”	缺少Webhook ID	点击Create webhook。
检查中出现“Webhook not found”	Webhook已在PayPal中被删除或属于另一个应用	再次点击Create webhook。
提示客户PayPal拒绝了该付款	PayPal拒绝了该资金来源	请客户选择其他支付来源。
客户看到“Too many pending requests”	有5个打开的订单	等待它们过期或完成它们。
PayPal按钮缺失	PayPal在Fees & limits中被关闭或未配置	开启并保存凭证。