# Швидкий старт з npx

> Одна команда налаштовує Perly Pay у вашому проєкті: маршрут оплати, маршрут вебхука з перевіркою підпису, кнопку Pay і ваш тестовий ключ.

`npx perly-pay init` читає ваш проєкт, пише код під його фреймворк і лишає вас за одне натискання від тестової оплати. Він налаштовує лише **тестовий режим**; живий вмикається в кабінеті.

> **Увага:** Пакет `perly-pay` уже на шляху до npm. Доки його там немає, ідіть за [Швидким стартом](https://pay.perly.io/docs/quick-start.md): той самий код, руками.

## Запуск

```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` (`/api/perly-pay/checkout` у Next.js). Він відкриває рахунок і веде покупця його сплатити.
- **Вебхук.** `/perly-pay/webhook` перевіряє `Perly-Signature` на сирому тілі. На `invoice.fulfilled` викликає `grantAccess()` — єдине TODO, яке пишете ви.
- **Плани.** Разові продажі й пакети кредитів, у `PLANS` на початку основного модуля. План, його кредити й ваш id користувача їдуть у метаданих рахунку й повертаються у вебхуку.
- **Ключі.** `PERLY_PAY_SECRET_KEY` і `PERLY_PAY_WEBHOOK_SECRET` у `.env.local` (Next.js) або `.env`, а сам файл — у `.gitignore`.

> **Примітка:** init ніколи не замінює файл чи значення, які вже є. `--force` замінює.

## Підключіть вебхук

Perly Pay має дістатися адреси вебхука. Додайте її в 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
```

На ноутбуці публічну адресу дає тунель: `cloudflared tunnel --url http://localhost:3000`. Більше у [Вебхуках](https://pay.perly.io/docs/webhooks.md).

## Одна оплата в тестовому режимі

1. **Запустіть застосунок** — Express і Node читають `.env` через `node --env-file=.env` або dotenv.
2. **Відкрийте /perly-pay** — Натисніть **Pay with crypto**. Ви на сторінці оплати.
3. **Simulate payment** — Рахунок стає сплаченим, потім виконаним. Див. [Тестовий режим](https://pay.perly.io/docs/test-mode.md).
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` і зберігає її секрет. |
| `--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](https://pay.perly.io/docs/sdks.md).