시작하기

npx로 빠른 시작

명령 하나로 프로젝트에 Perly Pay를 설정합니다: 결제 라우트, 서명을 검증하는 웹훅 라우트, 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)으로 폼을 보냅니다. 청구서를 열고 구매자를 결제로 안내합니다.
웹훅. /perly-pay/webhook이 원본 본문으로 Perly-Signature를 검증합니다. invoice.fulfilled에서 grantAccess()를 부릅니다 — 직접 쓸 TODO는 이것 하나.
요금제. 1회 판매와 크레딧 패키지, 메인 모듈 맨 위의 PLANS에. 요금제, 크레딧, 내 사용자 id가 청구서 메타데이터에 실려 웹훅으로 돌아옵니다.
키. PERLY_PAY_SECRET_KEY와 PERLY_PAY_WEBHOOK_SECRET는 .env.local(Next.js) 또는 .env에, 그 파일은 .gitignore에. git이 이미 그 파일을 추적 중이면 init은 키를 쓰지 않고 추적을 해제하는 법을 알려 줍니다.

init은 이미 있는 파일이나 값을 절대 바꾸지 않습니다. --force는 바꿉니다.

웹훅 연결

Perly Pay가 웹훅 URL에 닿아야 합니다. 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

노트북에서는 터널이 공개 URL을 줍니다: cloudflared tunnel --url http://localhost:3000. 자세한 내용은 웹훅에서.

테스트 모드로 결제 한 번

1
앱 실행
Express와 Node는 node --env-file=.env나 dotenv로 .env를 읽습니다.
2
/perly-pay 열기
Pay with crypto를 누르세요. 결제 페이지가 열립니다.
3
Simulate payment
청구서가 결제됨, 그다음 이행됨이 됩니다. 테스트 모드를 보세요.
4
grantAccess 동작 확인
웹훅이 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`용 URL을 등록하고 그 비밀 값을 저장합니다.
`--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_…)와 라이브 웹훅을 만드세요.
앱이 도는 곳에 설정하세요. 코드는 그대로입니다. 나머지 API는 SDK에서.