Per iniziare

Guida rapida con npx

Un comando configura Perly Pay nel tuo progetto: la route di checkout, la route del webhook con verifica della firma, un pulsante Pay e la tua chiave di test.

Vedi come Markdown

npx perly-pay init legge il tuo progetto, scrive codice per il suo framework e ti lascia a un clic da un pagamento di test. Configura solo la modalità test; la modalità live si attiva nella dashboard.

Eseguilo

bash

npx perly-pay init

Rileva il framework e il gestore di pacchetti, apre Dashboard → Developers e chiede una chiave di test (sk_test_…). Rifiuta una chiave live.

Cosa scrive

Framework	Come lo rileva	File
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	qualsiasi altro `package.json`	`lib/perly-pay.js`, `perly-pay.js` (`node:http`)

TypeScript o JavaScript, moduli ES o CommonJS, come il tuo progetto, e in src/ se il tuo codice è lì. npm, pnpm, yarn, bun e Composer.

Checkout. Il pulsante invia un form a /perly-pay/checkout (/api/perly-pay/checkout in Next.js). Apre una fattura e porta l’acquirente a pagarla.
Webhook. /perly-pay/webhook verifica Perly-Signature sul body grezzo. Con invoice.fulfilled chiama grantAccess(), l’unico TODO che scrivi tu.
Piani. Vendite una tantum e pacchetti di crediti, in PLANS in cima al modulo principale. Il piano, i suoi crediti e il tuo id utente viaggiano nei metadati della fattura e tornano nel webhook.
Chiavi. PERLY_PAY_SECRET_KEY e PERLY_PAY_WEBHOOK_SECRET in .env.local (Next.js) o .env, e il file in .gitignore. Se git traccia già quel file, init non ci scrive la chiave e ti dice come smettere di tracciarlo.

init non sostituisce mai un file o un valore già presente. --force sì.

Collega il webhook

Perly Pay deve poter raggiungere l’indirizzo del webhook. Aggiungilo in Dashboard → Developers → Webhooks per invoice.fulfilled e incolla il suo segreto whsec_… in PERLY_PAY_WEBHOOK_SECRET. Oppure lascia che init faccia entrambe le cose:

bash

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

Su un portatile, un tunnel ti dà un indirizzo pubblico: cloudflared tunnel --url http://localhost:3000. Altro in Webhook.

Un pagamento in modalità test

1
Avvia la tua app
Express e Node leggono .env con node --env-file=.env o dotenv.
2
Apri /perly-pay
Tocca Pay with crypto. Sei sul checkout.
3
Simulate payment
La fattura diventa pagata e poi consegnata. Vedi Modalità test.
4
Guarda grantAccess in azione
Il tuo webhook riceve invoice.fulfilled. Ora scrivi cosa concede.

Con un assistente AI

--yes non chiede nulla, quindi Claude Code, Cursor o Codex possono eseguirlo per te. Dagli la chiave e cosa vendi:

bash

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

--json stampa un risultato che l’assistente può leggere.

Opzioni

Flag	Cosa fa
`--yes`, `-y`	Nessuna domanda. Per assistenti AI e script.
`--framework <name>`	`next`, `express`, `hono`, `laravel` o `node`, se non l’ha indovinato.
`--key <sk_test_…>`	La tua chiave di test. Di default: `PERLY_PAY_SECRET_KEY`, oppure la chiede.
`--webhook-url <url>`	Registra l’indirizzo per `invoice.fulfilled` e salva il suo segreto.
`--product <name>`, `--amount <cents>`, `--currency <code>`	Cosa vendi, in USD o EUR. `--amount 4900` è $49.00.
`--install`	Installa anche l’SDK. Altrimenti stampa il comando.
`--force`	Sostituisce i file e i valori già presenti.
`--plugin`, `--mcp`	Stampa come aggiungere il plugin di Claude Code e il server `perly-pay-mcp`.
`--dry-run`	Dice cosa farebbe, senza scrivere nulla.
`--json`	Stampa il risultato come JSON.
`--api <origin>`, `--dir <path>`	Un altro Perly Pay (locale), un’altra cartella.

Modalità live

Collega le chiavi live del tuo wallet in Dashboard → Wallets.
Crea una chiave live (sk_live_…) e un webhook live.
Impostali dove gira la tua app. Il codice resta uguale. Il resto dell’API è negli SDK.