入门

用 npx 快速开始

一条命令在你的项目中设置好 Perly Pay：付款路由、带签名校验的 Webhook 路由、Pay 按钮和你的测试密钥。

npx perly-pay init 读取你的项目，按其框架写代码，让你离一次测试付款只差一次点击。它只设置测试模式；正式模式在控制台中开启。

运行

bash

npx perly-pay init

它会识别框架和包管理器，打开 Dashboard → Developers，并要求输入测试密钥（sk_test_…）。正式密钥会被拒绝。

它写什么

框架	识别依据	文件
Next.js (App Router)	`next`	`lib/perly-pay.ts`, `app/api/perly-pay/checkout/route.ts`, `app/api/perly-pay/webhook/route.ts`, `components/PayButton.tsx`, `app/perly-pay/page.tsx`
Express	`express`	`lib/perly-pay.js`, `routes/perly-pay.js`
Hono	`hono`	`lib/perly-pay.ts`, `routes/perly-pay.ts`
Laravel	`artisan`, `laravel/framework`	`app/Http/Controllers/PerlyPayController.php`, `routes/perly-pay.php`, `config/perly-pay.php`, `resources/views/perly-pay/button.blade.php`
Node.js	其他任何 `package.json`	`lib/perly-pay.js`, `perly-pay.js` (`node:http`)

TypeScript 还是 JavaScript、ES 模块还是 CommonJS — 与你的项目一致；代码在 src/ 里时也写到那里。支持 npm、pnpm、yarn、bun 和 Composer。

付款。 按钮把表单提交到 /perly-pay/checkout（Next.js 中为 /api/perly-pay/checkout）。它开出一张账单，并引导买家去支付。
Webhook。 /perly-pay/webhook 在原始请求体上校验 Perly-Signature。收到 invoice.fulfilled 时调用 grantAccess() — 这是唯一需要你自己写的 TODO。
方案。 一次性销售和额度包，定义在主模块开头的 PLANS 中。方案、它的额度和你的用户 id 放在账单元数据里，并随 Webhook 返回。
密钥。 PERLY_PAY_SECRET_KEY 和 PERLY_PAY_WEBHOOK_SECRET 写入 .env.local（Next.js）或 .env，该文件本身加入 .gitignore。如果 git 已在跟踪这个文件，init 不会把密钥写进去，并提示如何取消跟踪。

init 绝不替换已存在的文件或值。--force 才会替换。

连接 Webhook

Perly Pay 必须能访问到 Webhook 地址。在 Dashboard → Developers → Webhooks 中为 invoice.fulfilled 添加它，并把它的 whsec_… 密钥填入 PERLY_PAY_WEBHOOK_SECRET。或者让 init 完成这两步：

bash

npx perly-pay init --webhook-url https://your-app.example/perly-pay/webhook

在笔记本电脑上，用隧道获得公网地址：cloudflared tunnel --url http://localhost:3000。更多见 Webhook。

在测试模式下付一次款

1
启动应用
Express 和 Node 通过 node --env-file=.env 或 dotenv 读取 .env。
2
打开 /perly-pay
点击 Pay with crypto。你来到付款页。
3
Simulate payment
账单变为已付款，然后变为已交付。见测试模式。
4
看 grantAccess 运行
你的 Webhook 收到 invoice.fulfilled。现在写下它要授予什么。

配合 AI 助手

--yes 不提任何问题，所以 Claude Code、Cursor 或 Codex 可以替你运行它。给出密钥和你出售的东西：

bash

npx perly-pay init --yes --key sk_test_… --product "Logo review" --amount 4900

--json 打印助手能读取的结果。

参数

参数	作用
`--yes`, `-y`	不提问。适用于 AI 助手和脚本。
`--framework <name>`	猜错时指定 `next`、`express`、`hono`、`laravel` 或 `node`。
`--key <sk_test_…>`	你的测试密钥。默认读取 `PERLY_PAY_SECRET_KEY`，否则会询问。
`--webhook-url <url>`	为 `invoice.fulfilled` 注册该地址并保存其密钥。
`--product <name>`, `--amount <cents>`, `--currency <code>`	你出售的东西，以 USD 或 EUR 计价。`--amount 4900` 即 $49.00。
`--install`	同时安装 SDK。否则只打印命令。
`--force`	替换已存在的文件和值。
`--plugin`, `--mcp`	打印如何添加 Claude Code 插件和 `perly-pay-mcp` 服务器。
`--dry-run`	说明会做什么，但不写入任何内容。
`--json`	以 JSON 打印结果。
`--api <origin>`, `--dir <path>`	另一个 Perly Pay（本地的）、另一个目录。

正式模式

在 Dashboard → Wallets 中连接正式钱包公钥。
创建正式密钥（sk_live_…）和正式 Webhook。
在应用运行的环境中设置它们。代码保持不变。其余 API 见 SDK。