Початок

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

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

Відкрити як Markdown

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

Пакет perly-pay уже на шляху до npm. Доки його там немає, ідіть за Швидким стартом: той самий код, руками.

Запуск

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. Більше у Вебхуках.

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

1
Запустіть застосунок
Express і Node читають .env через node --env-file=.env або dotenv.
2
Відкрийте /perly-pay
Натисніть Pay with crypto. Ви на сторінці оплати.
3
Simulate payment
Рахунок стає сплаченим, потім виконаним. Див. Тестовий режим.
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.