Start

Szybki start z npx

Jedno polecenie konfiguruje Perly Pay w Twoim projekcie: trasę płatności, trasę webhooka z weryfikacją podpisu, przycisk Pay i Twój klucz testowy.

Otwórz jako Markdown

npx perly-pay init czyta Twój projekt, pisze kod pod jego framework i zostawia Cię jedno kliknięcie od płatności testowej. Konfiguruje tylko tryb testowy; produkcyjny włącza się w panelu.

Uruchomienie

bash

npx perly-pay init

Wykrywa framework i menedżer pakietów, otwiera Dashboard → Developers i prosi o klucz testowy (sk_test_…). Klucz produkcyjny odrzuca.

Co pisze

Framework	Po czym go wykrywa	Pliki
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	dowolny inny `package.json`	`lib/perly-pay.js`, `perly-pay.js` (`node:http`)

TypeScript lub JavaScript, moduły ES lub CommonJS — jak w Twoim projekcie, i w src/, gdy kod tam jest. npm, pnpm, yarn, bun i Composer.

Płatność. Przycisk wysyła formularz na /perly-pay/checkout (/api/perly-pay/checkout w Next.js). Ten otwiera fakturę i prowadzi kupującego do zapłaty.
Webhook. /perly-pay/webhook weryfikuje Perly-Signature na surowym body. Na invoice.fulfilled wywołuje grantAccess() — jedyne TODO, które piszesz Ty.
Plany. Sprzedaże jednorazowe i pakiety kredytów, w PLANS na początku głównego modułu. Plan, jego kredyty i Twoje id użytkownika jadą w metadanych faktury i wracają w webhooku.
Klucze. PERLY_PAY_SECRET_KEY i PERLY_PAY_WEBHOOK_SECRET w .env.local (Next.js) lub .env, a sam plik — w .gitignore. Jeśli git już śledzi ten plik, init nie zapisuje w nim klucza i podpowiada, jak przestać go śledzić.

init nigdy nie zastępuje istniejącego pliku ani wartości. --force zastępuje.

Podłącz webhook

Perly Pay musi dotrzeć do adresu webhooka. Dodaj go w Dashboard → Developers → Webhooks dla invoice.fulfilled i wklej jego sekret whsec_… do PERLY_PAY_WEBHOOK_SECRET. Albo niech init zrobi oba kroki:

bash

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

Na laptopie publiczny adres daje tunel: cloudflared tunnel --url http://localhost:3000. Więcej w Webhookach.

Jedna płatność w trybie testowym

1
Uruchom aplikację
Express i Node czytają .env przez node --env-file=.env lub dotenv.
2
Otwórz /perly-pay
Kliknij Pay with crypto. Jesteś na stronie płatności.
3
Simulate payment
Faktura staje się opłacona, potem zrealizowana. Zobacz Tryb testowy.
4
Zobacz, jak działa grantAccess
Twój webhook dostaje invoice.fulfilled. Teraz napisz, co ma przyznawać.

Z asystentem AI

--yes o nic nie pyta, więc Claude Code, Cursor czy Codex uruchomią go za Ciebie. Podaj klucz i to, co sprzedajesz:

bash

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

--json drukuje wynik, który asystent odczyta.

Opcje

Flaga	Co robi
`--yes`, `-y`	Bez pytań. Dla asystentów AI i skryptów.
`--framework <name>`	`next`, `express`, `hono`, `laravel` lub `node`, gdy zgadnie źle.
`--key <sk_test_…>`	Twój klucz testowy. Domyślnie: `PERLY_PAY_SECRET_KEY`, albo pyta.
`--webhook-url <url>`	Rejestruje adres dla `invoice.fulfilled` i zapisuje jego sekret.
`--product <name>`, `--amount <cents>`, `--currency <code>`	Co sprzedajesz, w USD lub EUR. `--amount 4900` to $49.00.
`--install`	Dodatkowo instaluje SDK. W przeciwnym razie drukuje polecenie.
`--force`	Zastępuje istniejące pliki i wartości.
`--plugin`, `--mcp`	Drukuje, jak dodać wtyczkę Claude Code i serwer `perly-pay-mcp`.
`--dry-run`	Mówi, co by zrobił, nic nie zapisuje.
`--json`	Drukuje wynik jako JSON.
`--api <origin>`, `--dir <path>`	Inny Perly Pay (lokalny), inny katalog.

Tryb produkcyjny

Podłącz produkcyjne klucze portfela w Dashboard → Wallets.
Utwórz klucz produkcyjny (sk_live_…) i produkcyjny webhook.
Ustaw je tam, gdzie działa aplikacja. Kod zostaje bez zmian. Reszta API — w SDK.