# 用 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](https://pay.perly.io/docs/webhooks.md)。

## 在测试模式下付一次款

1. **启动应用** — Express 和 Node 通过 `node --env-file=.env` 或 dotenv 读取 `.env`。
2. **打开 /perly-pay** — 点击 **Pay with crypto**。你来到付款页。
3. **Simulate payment** — 账单变为已付款，然后变为已交付。见[测试模式](https://pay.perly.io/docs/test-mode.md)。
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](https://pay.perly.io/docs/sdks.md)。