---
title: PayPal
description: 将 PayPal 连接至 NexCMP 以实现钱包充值——支持 REST 应用凭据、Webhook、沙箱测试和保存的 PayPal 账户。
url: https://nexcmp.com/zh-cn/docs/billing/paypal/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# PayPal

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

## 功能说明 {#what-it-does}

允许客户使用其 PayPal 余额、银行账户或保存在 PayPal 的银行卡为其 USD 钱包充值。客户还可以让 NexCMP 记住其 PayPal 账户以便进行 [automatic top-up](https://nexcmp.com/zh-cn/docs/billing/auto-top-up/)。对于偏好 PayPal 的客户，可将其与 [Stripe](https://nexcmp.com/zh-cn/docs/billing/stripe/) 搭配使用。

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| 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** 对话框会显示是否同时具备这两个权限域。 |
| 依赖项 | 无。 |

## 准备基础设施 {#prepare-the-infrastructure}

1. 使用您的企业账户登录 [developer.paypal.com](https://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中连接 {#connect-in-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**。

![已输入沙盒模式和示例凭据的PayPal页面](https://nexcmp.com/zh-cn/docs/images/billing/paypal-01-keys.webp)


### Webhook事件 {#webhook-events}

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获取该捕获。

## 验证 {#verify}

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是分开的）。

## 限制与注意事项 {#limits-notes}

- **付款如何完成。** 订单以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](https://nexcmp.com/zh-cn/docs/billing/auto-top-up/)）时，PayPal会将支付令牌存储在其金库中。NexCMP只保留一个标识符和PayPal电子邮箱。请参见[Saved payment methods](https://nexcmp.com/zh-cn/docs/billing/saved-payment-methods/)。
- **退款和争议**的处理方式与Stripe类似：退款请求在**Finance › Payouts › Card refunds**下审批；争议会冻结客户的账户并暂停其预付费服务，直到您解决争议。
- **费用。** PayPal的费用不会被读回；您配置的百分比和固定费用决定了客户看到的内容以及入账的金额。实际费率取决于您的国家/地区（表单提示越南为4.4%，美国为3.49%）。

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| "客户端 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**中被关闭或未配置 | 开启并保存凭证。 |