Başlangıç

npx ile hızlı başlangıç

Tek komut Perly Pay'i projende kurar: ödeme rotası, imza doğrulamalı webhook rotası, Pay butonu ve test anahtarın.

npx perly-pay init projeni okur, kodu framework'üne göre yazar ve seni bir test ödemesine tek tık uzaklıkta bırakır. Yalnızca test modunu kurar; canlı mod panelden açılır.

Çalıştırma

bash

npx perly-pay init

Framework'ü ve paket yöneticisini bulur, Dashboard → Developers'ı açar ve test anahtarını (sk_test_…) ister. Canlı anahtarı reddeder.

Ne yazar

Framework	Neye bakarak bulur	Dosyalar
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	başka herhangi bir `package.json`	`lib/perly-pay.js`, `perly-pay.js` (`node:http`)

TypeScript ya da JavaScript, ES modülleri ya da CommonJS — projendeki gibi; kod oradaysa src/ içinde. npm, pnpm, yarn, bun ve Composer.

Ödeme. Buton formu /perly-pay/checkout adresine gönderir (Next.js'te /api/perly-pay/checkout). Bu rota bir fatura açar ve alıcıyı ödemeye yönlendirir.
Webhook. /perly-pay/webhook, Perly-Signature'ı ham gövde üzerinde doğrular. invoice.fulfilled geldiğinde grantAccess() çağırır — senin yazacağın tek TODO.
Planlar. Tek seferlik satışlar ve kredi paketleri, ana modülün başındaki PLANS içinde. Plan, kredileri ve kullanıcı id'n fatura metadata'sında gider ve webhook'ta geri gelir.
Anahtarlar. PERLY_PAY_SECRET_KEY ve PERLY_PAY_WEBHOOK_SECRET, .env.local (Next.js) ya da .env içinde; dosyanın kendisi .gitignore'da. git bu dosyayı zaten izliyorsa init anahtarı oraya yazmaz ve izlemeden nasıl çıkarılacağını söyler.

init var olan bir dosyayı ya da değeri asla değiştirmez. --force değiştirir.

Webhook'u bağla

Perly Pay'in webhook adresine ulaşabilmesi gerekir. Adresi Dashboard → Developers → Webhooks'ta invoice.fulfilled için ekle ve whsec_… secret'ını PERLY_PAY_WEBHOOK_SECRET içine yapıştır. Ya da iki adımı da init yapsın:

bash

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

Dizüstü bilgisayarda herkese açık adresi bir tünel verir: cloudflared tunnel --url http://localhost:3000. Fazlası Webhook'lar sayfasında.

Test modunda bir ödeme

1
Uygulamayı başlat
Express ve Node, .env'i node --env-file=.env ya da dotenv ile okur.
2
/perly-pay'i aç
Pay with crypto'ya bas. Ödeme sayfasındasın.
3
Simulate payment
Fatura önce ödendi, sonra teslim edildi olur. Bkz. Test modu.
4
grantAccess'in çalıştığını gör
Webhook'un invoice.fulfilled alır. Şimdi ne vereceğini yaz.

Bir AI asistanıyla

--yes hiçbir şey sormaz, bu yüzden Claude Code, Cursor ya da Codex onu senin yerine çalıştırabilir. Anahtarı ve ne sattığını ver:

bash

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

--json, asistanın okuyabileceği bir sonuç yazdırır.

Seçenekler

Bayrak	Ne yapar
`--yes`, `-y`	Soru sormaz. AI asistanları ve scriptler için.
`--framework <name>`	Yanlış tahmin edildiğinde `next`, `express`, `hono`, `laravel` ya da `node`.
`--key <sk_test_…>`	Test anahtarın. Varsayılan: `PERLY_PAY_SECRET_KEY`, yoksa sorar.
`--webhook-url <url>`	`invoice.fulfilled` için adresi kaydeder ve secret'ını saklar.
`--product <name>`, `--amount <cents>`, `--currency <code>`	Ne sattığın, USD ya da EUR olarak. `--amount 4900`, $49.00 demek.
`--install`	SDK'yı da kurar. Yoksa komutu yazdırır.
`--force`	Var olan dosyaları ve değerleri değiştirir.
`--plugin`, `--mcp`	Claude Code eklentisinin ve `perly-pay-mcp` sunucusunun nasıl ekleneceğini yazdırır.
`--dry-run`	Ne yapacağını söyler, hiçbir şey yazmaz.
`--json`	Sonucu JSON olarak yazdırır.
`--api <origin>`, `--dir <path>`	Başka bir Perly Pay (yerel), başka bir klasör.

Canlı mod

Canlı cüzdan anahtarlarını Dashboard → Wallets'ta bağla.
Canlı bir anahtar (sk_live_…) ve canlı bir webhook oluştur.
Bunları uygulamanın çalıştığı yerde ayarla. Kod olduğu gibi kalır. API'nin geri kalanı SDK'lar sayfasında.