البداية

بداية سريعة مع npx

أمر واحد يعدّ Perly Pay في مشروعك: مسار الدفع، ومسار ويب هوك مع التحقق من التوقيع، وزر Pay، ومفتاح الاختبار الخاص بك.

يقرأ npx perly-pay init مشروعك، ويكتب الكود لإطار عمله، ويتركك على بُعد نقرة من دفعة تجريبية. يعدّ وضع الاختبار فقط؛ أما الوضع الحقيقي فيُفعَّل في لوحة التحكم.

التشغيل

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 أعلى الوحدة الرئيسية. تنتقل الخطة ورصيدها ومعرّف المستخدم لديك في بيانات الفاتورة الوصفية وتعود في الويب هوك.
المفاتيح. PERLY_PAY_SECRET_KEY وPERLY_PAY_WEBHOOK_SECRET في .env.local (Next.js) أو .env، والملف نفسه في .gitignore. إن كان git يتتبّع هذا الملف بالفعل، لا يكتب init المفتاح فيه ويشرح كيف تزيله من التتبّع.

لا يستبدل 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. الآن اكتب ما يمنحه.

مع مساعد ذكاء اصطناعي

--yes لا يسأل شيئًا، لذا يشغّله Claude Code أو Cursor أو Codex نيابةً عنك. أعطه المفتاح وما تبيعه:

bash

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

--json يطبع نتيجة يقرؤها المساعد.

الخيارات

العلَم	ما يفعله
`--yes`, `-y`	بلا أسئلة. لمساعدي الذكاء الاصطناعي والسكربتات.
`--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>`	ما تبيعه، بالدولار الأمريكي أو اليورو. `--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.