# 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.

`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.

> **Note:** 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](https://pay.perly.io/docs/webhooks.md).

## 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](https://pay.perly.io/docs/test-mode.md).
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](https://pay.perly.io/docs/sdks.md).