Next.js网站PayPal集成实战：从沙箱测试到生产环境部署的完整指南

上一篇介绍了如何申请 PayPal 个人卖家账户，这篇接着讲怎么把 PayPal 接入到自己的网站里。

我的项目基于 Next.js 构建，整个集成流程走下来，核心代码并不复杂，但中途踩了几个典型的坑，这里一并记录下来，希望能帮你节省时间。

获取 API 凭据

首先，登录 PayPal 开发者后台：https://developer.paypal.com/。注意页面左上角可以切换 Sandbox（测试）和 Live（生产）环境。

我们首先在 Sandbox 环境下进行测试。点击左侧导航栏的 “Apps & Credentials”，然后点击 “Create App”。

在创建应用的界面，填写你的应用名称（App Name），类型（Type）选择 Merchant，然后点击创建按钮。

创建完成后，页面会展示你的 Client ID 和 Secret。这两个值是调用 PayPal API 的钥匙，非常重要。

接下来，将这两个值安全地存储到你的项目环境变量文件中，例如 .env.local：

PAYPAL_CLIENT_ID=你的ClientID
PAYPAL_CLIENT_SECRET=你的Secret
PAYPAL_MODE=sandbox

当你在 Sandbox 环境下测试无误后，需要切换到 Live 环境，按照同样的流程重新创建一个应用，以获取生产环境的凭据。届时，只需将 PAYPAL_MODE 变量的值改为 live 即可。

集成方式选择

PayPal 提供了多种接入方式，你可以根据实际业务需求和技术栈进行选择。

方式一：PayPal.Me 链接

这是最简单的方式。在 PayPal 个人后台开启 PayPal.Me 功能，你会得到一个专属收款链接（例如 paypal.me/YourName）。直接将此链接发给买家，对方打开后输入金额即可完成付款。这种方式完全无需编码，非常适合社交媒体交易、朋友间转账等场景。

开通地址：https://www.paypal.com/paypalme/my/settings

方式二：支付按钮 / 付款链接（No-Code）

在 PayPal 商家后台，你可以直接创建付款链接和对应的二维码，这适合还没有独立网站的情况。你也可以生成一个“立即购买”按钮的 HTML 代码，直接复制粘贴到你的网页中。这种方式非常适合个人博客售卖电子书、工具网站提供付费下载等简单场景，无需开发能力，但定制性较弱。

创建地址：https://www.paypal.com/ncp/links/create

简单来说，如果你销售的是固定价格的产品或服务，使用这里的付款链接更合适；如果是接受金额不确定的打赏，则 PayPal.Me 链接更灵活。

方式三：JavaScript SDK

在你的网页中嵌入 PayPal 提供的 JavaScript SDK，页面上会渲染出 PayPal 按钮。用户点击后，支付窗口会在当前页面弹出，无需跳转。这种方案集成速度快，官方声称15分钟即可跑通，适合以前端为主、后端逻辑较轻的项目。

JS SDK 的集成指南位于官方文档：https://developer.paypal.com/docs/checkout/standard/integrate/

方式四：REST API（Orders API）

通过后端服务器直接调用 PayPal 的 REST API，完全自主控制整个支付流程。这种方案灵活性最高，但需要编写后端代码。它适合那些拥有自己订单系统、需要将支付与复杂业务逻辑深度集成的项目。

我的网站基于 Next.js，已经有一套订单系统，需要在支付成功后触发自动处理、发送邮件等后续流程，因此我选择了第四种方案。

其核心流程如下：

1. 用户在我的网站点击 PayPal 支付。
2. 后端调用 PayPal API 创建订单，并获取一个用于跳转的 approval_url。
3. 前端将用户重定向至 PayPal 的支付页面。
4. 用户在 PayPal 页面完成支付。
5. PayPal 将用户重定向回我预设的网站返回地址。
6. 后端调用 PayPal API 确认并捕获（Capture）该笔支付。
7. 更新我自身数据库的订单状态，并触发后续业务逻辑。

这里我使用的是 Return URL 同步回调模式，并未使用 Webhook。对于当前项目的业务量级来说，这已经足够可靠且实现简单。Webhook 虽然更稳健（能处理用户未成功返回网站的情况），但需要额外进行签名验证，配置稍显复杂，可以待业务增长后再行考虑。

测试环境实操指南

在 Sandbox 环境下，我们需要使用测试账号来模拟真实的支付流程。

在开发者后台，点击 Sandbox -> Accounts，你会看到 PayPal 自动为你生成的两个测试账号：一个 Personal（模拟买家），一个 Business（模拟卖家）。

点击 Personal 账号右侧的“...”菜单，选择 View/Edit Account，即可查看该测试账号的登录邮箱和密码。

在测试支付时，使用这个买家测试账号登录即可，整个过程不会产生真实的资金流动。

如果你想测试信用卡支付，可以使用以下测试卡号信息（请注意，我个人未逐一验证）：

• Visa: 4032039668297305
• Mastercard: 5425233430109903
• CVV 任意填写3位数字，过期日期填写未来的日期。
• 重要：账单地址需要填写美国地址，如果填写中国地址，通常会报错。

集成过程中遇到的“坑”

坑 1：测试前需退出卖家账户

在 Sandbox 环境测试支付流程时，如果你的浏览器当前登录着卖家（Business）测试账号，访问付款页面可能会报错，提示“您当前是商家账号”等类似信息。这是因为 PayPal 不允许商家账号向自己付款。

解决方法：测试支付前，请先退出当前的卖家账号，或者直接使用浏览器的无痕/隐私模式打开支付链接，再用买家测试账号进行操作。

坑 2：中国买家无法付款给中国卖家

这是一个由 PayPal 政策导致的限制。如果你的 PayPal 账户注册地是中国，那么当账单地址同样在中国的买家尝试使用借记卡或信用卡付款时，会看到如下提示：“很抱歉，账单地址在中国的买家不能使用PayPal付款给注册地在中国的卖家。”

解决办法通常有两种：

1. 使用香港、美国等地区的 PayPal 企业账户进行收款。
2. 为国内用户提供其他支付渠道，例如支持支付宝/微信支付的 Stripe 等。

其他补充建议

为网站接入多种收款方式，可以显著提升买家的付款成功率。不要只依赖 PayPal，可以根据你的用户分布，考虑搭配 Stripe、支付宝国际版等支付工具。

善用 Guest Checkout（访客支付）：PayPal 支持非注册用户直接使用信用卡付款。在支付页面，用户可以选择“使用借记卡或信用卡付款”选项，无需创建或登录 PayPal 账户。这降低了支付门槛，对提升转化率很有帮助。

关于 PayPal 的汇率计算、资金提现到国内银行卡的路径及损耗等问题，涉及的内容较多，如果你感兴趣，我们可以在 云栈社区 后续的分享中详细探讨。收款环节的打通是产品出海的关键一步，希望这篇实战记录能为你扫清一些障碍。