Démarrer

Démarrage rapide avec npx

Une commande installe Perly Pay dans votre projet : une route de paiement, une route de webhook qui vérifie les signatures, un bouton Pay et votre clé de test.

Voir en Markdown

npx perly-pay init lit votre projet, écrit le code pour son framework et vous laisse à un clic d’un paiement de test. Il ne configure que le mode test ; le passage en réel se fait dans le tableau de bord.

Lancez-le

bash

npx perly-pay init

Il détecte le framework et le gestionnaire de paquets, ouvre Dashboard → Developers et demande une clé de test (sk_test_…). Une clé réelle est refusée.

Ce qu’il écrit

Framework	Détecté par	Fichiers
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	tout autre `package.json`	`lib/perly-pay.js`, `perly-pay.js` (`node:http`)

TypeScript ou JavaScript, modules ES ou CommonJS, comme votre projet, et sous src/ si votre code s’y trouve. npm, pnpm, yarn, bun et Composer.

Paiement. Le bouton envoie un formulaire à /perly-pay/checkout (/api/perly-pay/checkout dans Next.js). Il ouvre une facture et envoie l’acheteur la payer.
Webhook. /perly-pay/webhook vérifie Perly-Signature sur le corps brut. Sur invoice.fulfilled, il appelle grantAccess() : le seul TODO à remplir par vous.
Offres. Ventes uniques et packs de crédits, dans PLANS en haut du module principal. L’offre, ses crédits et votre id utilisateur voyagent dans les métadonnées de la facture et reviennent dans le webhook.
Clés. PERLY_PAY_SECRET_KEY et PERLY_PAY_WEBHOOK_SECRET dans .env.local (Next.js) ou .env, et ce fichier dans .gitignore. Si git suit déjà ce fichier, init n’y écrit aucune clé et explique comment le retirer du suivi.

init ne remplace jamais un fichier ou une valeur déjà présents. --force le fait.

Branchez le webhook

Perly Pay doit pouvoir joindre l’URL du webhook. Ajoutez-la dans Dashboard → Developers → Webhooks pour invoice.fulfilled et collez son secret whsec_… dans PERLY_PAY_WEBHOOK_SECRET. Ou laissez init faire les deux :

bash

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

Sur votre ordinateur portable, un tunnel donne une URL publique : cloudflared tunnel --url http://localhost:3000. Plus de détails dans Webhooks.

Un paiement en mode test

1
Lancez votre app
Express et Node lisent .env avec node --env-file=.env, ou avec dotenv.
2
Ouvrez /perly-pay
Touchez Pay with crypto. Vous arrivez sur la caisse.
3
Simulate payment
La facture passe à payée, puis à honorée. Voir Mode test.
4
Regardez grantAccess tourner
Votre webhook reçoit invoice.fulfilled. Écrivez maintenant ce qu’il accorde.

Avec un assistant IA

--yes ne pose aucune question : Claude Code, Cursor ou Codex peuvent le lancer pour vous. Donnez-lui la clé et ce que vous vendez :

bash

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

--json affiche le résultat pour que l’assistant le lise.

Options

Option	Effet
`--yes`, `-y`	Aucune question. Pour les assistants IA et les scripts.
`--framework <name>`	`next`, `express`, `hono`, `laravel` ou `node`, si la détection se trompe.
`--key <sk_test_…>`	Votre clé de test. Par défaut : `PERLY_PAY_SECRET_KEY`, sinon il la demande.
`--webhook-url <url>`	Enregistre l’URL pour `invoice.fulfilled` et garde son secret.
`--product <name>`, `--amount <cents>`, `--currency <code>`	Ce que vous vendez, en USD ou EUR. `--amount 4900` vaut 49,00 $.
`--install`	Installe aussi le SDK. Sinon, affiche la commande.
`--force`	Remplace les fichiers et valeurs déjà présents.
`--plugin`, `--mcp`	Affiche comment ajouter le plugin Claude Code et le serveur `perly-pay-mcp`.
`--dry-run`	Dit ce qu’il ferait, sans rien écrire.
`--json`	Affiche le résultat en JSON.
`--api <origin>`, `--dir <path>`	Un autre Perly Pay (local), un autre dossier.

Passer en réel

Connectez les clés de votre portefeuille réel dans Dashboard → Wallets.
Créez une clé réelle (sk_live_…) et un endpoint de webhook réel.
Définissez-les là où tourne votre app. Le code reste tel quel. Le reste de l’API est dans SDK.