接入 Paypal 支付

按照以下步骤为你的项目接入 Paypal 支付。

开通 Paypal 商户

参考 Paypal 商家入驻指南 开通 Paypal 商户。

查看 API 密钥

使用正式的 Paypal 商户账号和密码，登录 Paypal 商户后台，查看支付密钥。

API Credentials 下面的 API Key 和 Secret 是 Paypal 收款的 API 密钥。

Sandbox credentials 下面的 Username 和 Password 是 Paypal 测试环境的账号和密码。

本地测试时，请切换到 Sandbox 环境，正式上线时，切换到 Live 环境。

配置 Paypal 支付

在项目管理后台，进入 Settings -> Payment -> Paypal 面板，在 Paypal Client ID 和 Paypal Client Secret 字段分别填入上一步设置的 API Key 和 Secret。

Paypal Webhook ID 是验证支付通知的签名密钥，可以先留空，等在后续步骤配置了支付通知后再填入。

获取 Paypal 测试账号

使用正式的 Paypal 商户账号和密码，登录 Paypal 开发者后台，进入 Testing Tools -> Sandbox Accounts 页面，选择 Personal 类型的账号，点击进入复制 Email 和 Password，可以用作测试环境 Paypal 支付调试。

支付验证

访问项目的 /pricing 页面，查看默认的价格表，选择一个价格方案，点击下单按钮。

在弹出的支付方式选择框选择 Paypal，如果能正常跳转到 Paypal 支付页面，说明支付配置成功。

在 Paypal 支付页面，使用上一步获取的 Paypal 测试账户登录，验证 Paypal 支付功能。

查看交易记录

使用第二步 Sandbox credentials 下的 Username和 Password 登录 Paypal 测试商户后台，查看测试环境的交易订单。

如果是正式环境，则使用正式的商户账号和密码登录 Paypal 商户后台 查看真实的交易订单。

设计价格表

默认的价格表配置在 src/config/locale/messages/{locale}/pages/pricing.json文件中，支持多语言，每个 locale 对应一个独立的价格表配置。

项目价格表跟支付供应商无关。接入 Paypal 支付时，价格表设计可参考 Stripe 支付的：设计价格表。

配置支付回调

用户在价格表页面选择价格方案下单成功后，会跳转到 Paypal 支付页面，支付成功后，会跳转到项目的回调接口：/api/payment/callback。

在回调接口中，会根据订单号更新订单状态，再跳转到配置的 callbackUrl。

这个配置的 callbackUrl 是在下单接口：/api/payment/checkout 中指定的：

const callbackUrl =

  paymentType === PaymentType.SUBSCRIPTION

    ? `${callbackBaseUrl}/settings/billing`

    : `${callbackBaseUrl}/settings/payments`;

按照默认配置，如果是一次性支付，最终会跳转到 /settings/payments 页面；如果是订阅支付，最终会跳转到 /settings/billing 页面。

你可以根据项目需求，自行修改用户支付完成后的跳转地址。

注意：支付回调是同步跳转的，如果用户在 Paypal 支付页面确认支付，在页面跳转前关闭了浏览器，未能正常跳转到项目回调接口，订单状态无法更新，用户在个人中心无法看到已支付的订单。此类情况叫做：丢单。

为了避免支付回调的 丢单 情况，建议项目上线运营时，在 Paypal 后台配置支付通知。

配置支付通知

添加支付通知地址

登录 Paypal 开发者后台，进入 Apps & Credentials 页面，选择默认的应用，划到最底部，点击 Add Webhook 按钮，添加支付通知地址。

• Webhook URL 输入接收通知的地址。必须是可以公网访问的 https 地址。格式为：
•  

https://{your-domain.com}/api/payment/notify/paypal

把 {your-domain.com} 替换为你的项目域名，可以是根域名，也可以是子域名。

• Event types 点击 All Events 选择全部事件。

或者也可以只勾选其中一部分事件。ShipAny 项目中支持处理的支付通知事件包括：

CHECKOUT.ORDER.APPROVED               # 单次付款已授权（可选，用于pending状态）

CHECKOUT.ORDER.COMPLETED              # 单次付款成功

BILLING.SUBSCRIPTION.ACTIVATED        # 订阅激活

BILLING.SUBSCRIPTION.CANCELLED        # 订阅取消

BILLING.SUBSCRIPTION.PAYMENT.FAILED   # 续费失败

PAYMENT.SALE.COMPLETED                # 订阅续费成功

PAYMENT.CAPTURE.REFUNDED              # 单次付款退款

PAYMENT.SALE.REFUNDED                 # 订阅退款

填写完配置后，点击 Save 按钮，添加支付通知地址。

复制支付通知签名密钥

创建完支付通知地址后，在支付通知列表页面，复制 Webhook ID，这是支付通知的签名密钥。

配置支付通知签名密钥

在项目管理后台，进入 Settings -> Payment -> Paypal 面板，在 Paypal Webhook ID 字段填入上一步复制的支付通知签名密钥。

本地调试支付通知

不同的支付供应商，本地调试支付通知的步骤一致。核心思路都是通过 内网穿透，把一个公网地址映射到本地开发机，然后在支付供应商后台配置支付通知地址时，填入这个公网地址。

比如通过 ngrok 实现 内网穿透 后，填入到 Paypal 后台的支付通知地址示例：

https://xxx.ngrok-free.app/api/payment/notify/paypal