はじめに

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 回支払う

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 で。