大白：独立开发者 PayPal 对接最佳实践指南

大白：独立开发者 PayPal 对接最佳实践指南大白：独立开发者 PayPal 对接最佳实践指南 Modified January 22 • 中国区个人账户 (Personal Account)： ◦ 限制：无法直接开具商业发票，提现需符合外汇管制。 ◦ 关键点：注册时必须填写真实中文姓名和身份证地址，绑定国内银行卡完成实名认证。 • 企业账户 (Business Account)： ◦ 适用场景：已有营业执照（含个体工商户）。 ◦ 优势：风控相对宽松，支持更多营销功能。 1.2 提现与结汇 (The Cash out Problem) • 痛点：PayPal 提现至国内个人银行卡常被拒收，且每笔手续费 $35。 • 推荐方案： a. 办个执照：注册国内“个体工商户”，开立义乌个体户账户或通过正规第三方结汇。 b. 香港卡：如有条件，办理香港银行卡，PayPal 提现港币免费（有汇率损耗）。 c. 以支代提：用于支付服务器 (AWS/Vercel)、域名、AI API 等海外开发成本。 2. 开发环境配置 (Development Setup) 2.1 获取凭证 (Credentials) 1. 登录 PayPal Developer Dashboard。 2. 进入 Apps & Credentials。 3. Sandbox (测试)：用于开发调试，产生虚拟交易。 4. Live (生产)：用于正式上线，产生真实交易。 5. 核心凭证： ◦ Client ID (客户端 ID)：公开的，用于前端和后端。 ◦ Secret (密钥)：绝对保密，仅存于后端服务器，严禁提交到 GitHub。 2.2 测试账号 (Sandbox Accounts) • 不要用你自己的开发者账号测试支付！ • 在 Developer Dashboard Testing Tools Sandbox Accounts 获取： ◦ Personal (Buyer)：买家账号，格式如 sb xxxx@personal.example.com。 ◦ Business (Seller)：卖家账号（通常就是你自己的 Developer 账号）。 3. 技术实现最佳实践 (Code Implementation) 推荐使用服务端集成 (Server Side Integration) 模式，比纯前端模式更安全，能防止金额篡改。 3.1 后端结构 (Node.js) 使用 dotenv 管理密钥，但需注意 Windows 下的文件路径读取问题。 Code block Plain Text Copy // server.js 核心逻辑摘要 import express from "express"; import fetch from "node fetch"; // 环境变量管理（生产环境务必使用环境变量，不要硬编码） const PAYPAL CLIENT ID = process.env.PAYPAL CLIENT ID; const PAYPAL CLIENT SECRET = process.env.PAYPAL CLIENT SECRET; // 根据环境切换 URL const base = process.env.NODE ENV === 'production' ? "https://api m.paypal.com" : "https://api m.sandbox.paypal.com"; // 1. 获取 Access Token (OAuth 2.0) const generateAccessToken = async () = { const auth = Buffer.from(PAYPAL CLIENT ID + ":" + PAYPAL CLIENT SECRET).toString("base64"); const response = await fetch( , { method: "POST", body: "grant type=client credentials", headers: { Authorization: }, }); const data = await response.json(); return data.access token; }; // 2. 创建订单 (Create Order) app.post("/api/orders", async (req, res) = { const accessToken = await generateAccessToken(); const response = await fetch( , { method: "POST", headers: { "Content Type": "application/json", Authorization: , }, body: JSON.stringify({ intent: "CAPTURE", purchase units: [{ amount: { currency code: "USD", value: "10.00" } // 生产环境请动态获取金额 }], }), }); // ...返回 json.id 给前端 }); // 3. 捕获资金 (Capture Order) app.post("/api/orders/:orderID/capture", async (req, res) = { // ...使用 accessToken 调用 capture 接口 }); 3.2 前端结构 (HTML/JS) 前端只负责展示按钮和传递 Order ID，不处理金额逻辑。 Code block Plain Text Copy <! index.html <! 务必注意：script 标签中的 client id 必须与后端配置一致 <script src="https://www.paypal.com/sdk/js?client id=YOUR PUBLIC CLIENT ID&currency=USD" </script <script paypal.Buttons({ // 调用后端创建订单 createOrder: async (data, actions) = { const response = await fetch("/api/orders", { method: "POST" }); const order = await response.json(); return order.id; // 返回 ID 给 PayPal }, // 用户付款后，调用后端扣款 onApprove: async (data, actions) = { const response = await fetch( , { method: "POST" }); const result = await response.json(); if (result.status === 'COMPLETED') { alert('支付成功！'); } } }).render(' paypal button container'); </script 4. 常见报错与避坑 (Troubleshooting) 🔴 错误：UNAUTHORIZED / invalid client • 原因：密钥填错，或者环境不匹配。 • 解决： ◦ 检查代码里的 URL 是 sandbox 还是 live。 ◦ 确保 Client ID 和 Secret 是对应环境的（Sandbox ID 不能用于 Live URL）。 ◦ 修改配置后务必重启 Node.js 服务器。 🔴 错误：Transaction refused / "您正在登录卖家的账户..." • 原因：自买自卖。你登录了与收款方相同的 PayPal 账号。 • 解决：必须使用沙盒环境的 Personal (Buyer) 虚拟账号登录付款。 🔴 错误：.env 文件读取失败 • 原因：Windows 系统下路径包含空格或中文，或者文件被存为 .env.txt。 • 解决：使用 path.resolve( dirname, '.env') 强制指定路径，或在本地测试时临时硬编码密钥（上线前需改回）。 5. 上线检查清单 (Go Live Checklist) • [ ] 密钥切换：将代码中的 Client ID / Secret 替换为 Live 版本。 • [ ] URL 切换：API 地址切换为 https://api m.paypal.com。 • [ ] 金额测试：将测试金额改为 $0.1 或 $1.0 进行真实资金测试。 • [ ] 日志脱敏：生产环境关闭 console.log 打印密钥或 Token 的功能。 • [ ] 错误处理：确保后端有 try catch 处理网络超时或 PayPal API 报错，避免服务器崩溃。最后建议：作为独立开发者，支付是生命线。不要将密钥硬编码提交到 GitHub 公共仓库。如果如果不慎泄露，请立即去 PayPal 后台 Revoke（撤销）旧密钥并生成新的。 Processing... Please wait 独立开发者 PayPal 对接最佳实践.md.pdf PayPal Developer Dashboard sb xxxx@personal.example.com • 中国区个人账户 (Personal Account)： ◦ 限制：无法直接开具商业发票，提现需符合外汇管制。 ◦ 关键点：注册时必须填写真实中文姓名和身份证地址，绑定国内银行卡完成实名认证。 ◦ 限制：无法直接开具商业发票，提现需符合外汇管制。 ◦ 关键点：注册时必须填写真实中文姓名和身份证地址，绑定国内银行卡完成实名认证。 • 企业账户 (Business Account)： ◦ 适用场景：已有营业执照（含个体工商户）。 ◦ 优势：风控相对宽松，支持更多营销功能。 ◦ 适用场景：已有营业执照（含个体工商户）。 ◦ 优势：风控相对宽松，支持更多营销功能。 1.2 提现与结汇 (The Cash out Problem) • 痛点：PayPal 提现至国内个人银行卡常被拒收，且每笔手续费 $35。 • 推荐方案： a. 办个执照：注册国内“个体工商户”，开立义乌个体户账户或通过正规第三方结汇。 b. 香港卡：如有条件，办理香港银行卡，PayPal 提现港币免费（有汇率损耗）。 c. 以支代提：用于支付服务器 (AWS/Vercel)、域名、AI API 等海外开发成本。 a. 办个执照：注册国内“个体工商户”，开立义乌个体户账户或通过正规第三方结汇。 b. 香港卡：如有条件，办理香港银行卡，PayPal 提现港币免费（有汇率损耗）。 c. 以支代提：用于支付服务器 (AWS/Vercel)、域名、AI API 等海外开发成本。 2. 开发环境配置 (Development Setup) 2.1 获取凭证 (Credentials) 1. 登录 PayPal Developer Dashboard。 PayPal Developer Dashboard 2. 进入 Apps & Credentials。 3. Sandbox (测试)：用于开发调试，产生虚拟交易。 4. Live (生产)：用于正式上线，产生真实交易。 5. 核心凭证： ◦ Client ID (客户端 ID)：公开的，用于前端和后端。 ◦ Secret (密钥)：绝对保密，仅存于后端服务器，严禁提交到 GitHub。 ◦ Client ID (客户端 ID)：公开的，用于前端和后端。 ◦ Secret (密钥)：绝对保密，仅存于后端服务器，严禁提交到 GitHub。 2.2 测试账号 (Sandbox Accounts) • 不要用你自己的开发者账号测试支付！ • 在 Developer Dashboard Testing Tools Sandbox Accounts 获取： ◦ Personal (Buyer)：买家账号，格式如 sb xxxx@personal.example.com。 ◦ Business (Seller)：卖家账号（通常就是你自己的 Developer 账号）。 sb xxxx@personal.example.com ◦ Personal (Buyer)：买家账号，格式如 sb xxxx@personal.example.com。 sb xxxx@personal.example.com ◦ Business (Seller)：卖家账号（通常就是你自己的 Developer 账号）。 3. 技术实现最佳实践 (Code Implementation) 推荐使用服务端集成 (Server Side Integration) 模式，比纯前端模式更安全，能防止金额篡改。 3.1 后端结构 (Node.js) 使用 dotenv 管理密钥，但需注意 Windows 下的文件路径读取问题。 3.2 前端结构 (HTML/JS) 前端只负责展示按钮和传递 Order ID，不处理金额逻辑。 4. 常见报错与避坑 (Troubleshooting) 🔴 错误：UNAUTHORIZED / invalid client • 原因：密钥填错，或者环境不匹配。 • 解决： ◦ 检查代码里的 URL 是 sandbox 还是 live。 ◦ 确保 Client ID 和 Secret 是对应环境的（Sandbox ID 不能用于 Live URL）。 ◦ 修改配置后务必重启 Node.js 服务器。 ◦ 检查代码里的 URL 是 sandbox 还是 live。 ◦ 确保 Client ID 和 Secret 是对应环境的（Sandbox ID 不能用于 Live URL）。 ◦ 修改配置后务必重启 Node.js 服务器。 🔴 错误：Transaction refused / "您正在登录卖家的账户..." • 原因：自买自卖。你登录了与收款方相同的 PayPal 账号。 • 解决：必须使用沙盒环境的 Personal (Buyer) 虚拟账号登录付款。 🔴 错误：.env 文件读取失败 • 原因：Windows 系统下路径包含空格或中文，或者文件被存为 .env.txt。 • 解决：使用 path.resolve( dirname, '.env') 强制指定路径，或在本地测试时临时硬编码密钥（上线前需改回）。 5. 上线检查清单 (Go Live Checklist) • [ ] 密钥切换：将代码中的 Client ID / Secret 替换为 Live 版本。 • [ ] URL 切换：API 地址切换为 https://api m.paypal.com。 • [ ] 金额测试：将测试金额改为 $0.1 或 $1.0 进行真实资金测试。 • [ ] 日志脱敏：生产环境关闭 console.log 打印密钥或 Token 的功能。 • [ ] 错误处理：确保后端有 try catch 处理网络超时或 PayPal API 报错，避免服务器崩溃。最后建议：作为独立开发者，支付是生命线。不要将密钥硬编码提交到 GitHub 公共仓库。如果如果不慎泄露，请立即去 PayPal 后台 Revoke（撤销）旧密钥并生成新的。最后建议：作为独立开发者，支付是生命线。不要将密钥硬编码提交到 GitHub 公共仓库。如果如果不慎泄露，请立即去 PayPal 后台 Revoke（撤销）旧密钥并生成新的。 Processing... Please wait 独立开发者 PayPal 对接最佳实践.md.pdf Processing... Please wait 独立开发者 PayPal 对接最佳实践.md.pdf 适用对象：中国大陆独立开发者（无公司实体 / 个人身份）技术栈：Node.js (Backend) + HTML/JS (Frontend) 对接模式：PayPal Standard Checkout (Server side Integration) 适用对象：中国大陆独立开发者（无公司实体 / 个人身份）技术栈：Node.js (Backend) + HTML/JS (Frontend) 对接模式：PayPal Standard Checkout (Server side Integration) 1. 账户与合规 (Account & Compliance) 1.1 账户类型选择 ◦ 适用场景：前期验证想法、小额收款。

在小宇宙note 阅读完整内容