مدفوعات العملات المشفرة لـ Marzban VPN
خدمة صغيرة تستضيفها بنفسك تبيع اشتراكات Marzban VPN بالعملات المشفرة عبر SnapEX Pay. يطلب منها متجرك أو بوت Telegram رابط دفع، فيدفع العميل على صفحة SnapEX Pay (USDT على TRC20 أو ERC20 أو BEP20، إضافةً إلى طرق أخرى يتيحها SnapEX لهذا المبلغ)، وبعد دفع الفاتورة تُنشئ الخدمة المستخدم في لوحة Marzban أو تُمدّد اشتراكه، وتُعيد رابط الاشتراك.
مجانًا. الإصدار 1.1.0.
ماذا تفعل الوحدة
- لا محفظة ولا عقدة بلوكتشين تحتاج إلى تشغيلها.
POST /v1/checkoutيُنشئ فاتورة SnapEX Pay لباقة ويُعيدpay_url؛ وGET /v1/orders/{invoice_id}يُعيد الحالة ورابط الاشتراك من سجلات الخدمة نفسها (يُحدّثها إشعار Webhook)، فيستطيع البوت الاستعلام عنه دوريًا.- إشعار Webhook موقّع (HMAC-SHA256، مع نافذة زمنية للطابع الزمني مدتها 5 دقائق). لا يُعتمد على محتوى إشعار Webhook أبدًا: تُقرأ الفاتورة من جديد من API SnapEX Pay، ولا يُجهَّز المستخدم إلا إذا كانت مدفوعة.
- آمن من التكرار: عمليات تسليم Webhook المكررة أو المتزامنة تُنفِّذ الفاتورة مرة واحدة فقط.
- يحصل المستخدمون الجدد على كل بروتوكول له inbound في لوحتك؛ ويُمدَّد اشتراك المستخدمين الحاليين من تاريخ انتهائه الحالي (أو من الآن إذا كان قد مضى أو لم يكن للمستخدم تاريخ انتهاء)، وفي باقات الترافيك تُضاف حصة الباقة إلى الحد الحالي أو إلى الترافيك المستهلك، أيهما أعلى.
- تُضبط الباقات بمتغير بيئة واحد؛ وتُحفظ الطلبات في SQLite. وضع الاختبار لا يحرّك أي أموال حقيقية.
التثبيت
- نزّل الأرشيف وفُكّ ضغطه، ثم نفّذ في مجلده
cp .env.example .env. - في لوحة تحكم التاجر في SnapEX Pay أنشئ مفتاح API بالصلاحيتين
invoices.readوinvoices.write، وضعه فيSNAPEX_API_KEY. - اضبط
API_TOKEN(مثلًاopenssl rand -hex 32)، وMARZBAN_URL، وبيانات دخول مشرف Marzban (MARZBAN_USERNAMEوMARZBAN_PASSWORD)، وباقاتك فيPLANS(id:days:usd:traffic_bytes، و0بايت = بلا حدود). - شغّل الخدمة:
docker compose up -d، ثم تحقّق عبرcurl http://127.0.0.1:8080/health. ضع الخدمة خلف وكيل عكسي يدعم HTTPS. - في لوحة التحكم ← للمطورين اضبط عنوان Webhook على
https://<your service>/webhook، وانسخ سر التوقيعwhsec_…(يظهر مرة واحدة فقط، عند حفظ العنوان أول مرة) إلىSNAPEX_WEBHOOK_SECRET، ثم أعد تشغيل الخدمة. - من متجرك أو البوت استدعِ
POST /v1/checkoutمعAuthorization: Bearer <API_TOKEN>، وأرسلpay_urlإلى العميل، واستعلم دوريًا عنGET /v1/orders/{invoice_id}للحصول على رابط الاشتراك. للاختبار دون أموال حقيقية اضبطSNAPEX_ENVIRONMENT=test.
الإعدادات
| SNAPEX_API_KEY | مفتاح API التاجر (smk_…) بالصلاحيتين invoices.read وinvoices.write. |
|---|---|
| SNAPEX_WEBHOOK_SECRET | سر التوقيع (whsec_…) لنقطة نهاية Webhook الخاصة بك. |
| SNAPEX_ENVIRONMENT | live أو test. الفواتير التجريبية لا تحرّك أي أموال حقيقية. |
| SNAPEX_FEE_ON | من يدفع عمولة خدمة SnapEX: merchant أو customer. |
| API_TOKEN | رمز Bearer الذي يرسله البوت أو المتجر إلى /v1/checkout و/v1/orders/*. |
| MARZBAN_URL, MARZBAN_USERNAME, MARZBAN_PASSWORD | عنوان اللوحة وبيانات دخول المشرف (أو MARZBAN_TOKEN جاهز؛ لكن الرموز تنتهي صلاحيتها، لذا فاسم المستخدم وكلمة المرور أفضل لخدمة تعمل لفترات طويلة). |
| PLANS | قيم id:days:usd:traffic_bytes مفصولة بفواصل، والافتراضي month:30:5.00:0,quarter:90:12.00:0. |
| SNAPEX_PARTNER_ID | اختياري: Partner ID للمُدمِج الذي أعدّ الوحدة (برنامج الإحالة في SnapEX Pay). اتركه فارغًا إذا أعددتها بنفسك. |
أسئلة
هل يمكنني استخدامها من بوت Telegram؟
نعم. يستدعي البوت POST /v1/checkout، ويرسل pay_url إلى المستخدم، ويستعلم دوريًا عن GET /v1/orders/{invoice_id} للحصول على رابط الاشتراك. ويتوفر أيضًا بوت Telegram متكامل لـ Marzban و3x-ui وRemnawave.
ماذا يحدث لمستخدم حالي يدفع مرة أخرى؟
يُمدَّد الاشتراك من تاريخ الانتهاء الحالي (أو من الآن إذا كان قد مضى أو لم يكن للمستخدم تاريخ انتهاء)؛ وفي باقات الترافيك تُضاف حصة الباقة إلى الحد الحالي أو إلى الترافيك المستهلك، أيهما أعلى.
هل يمكن لإشعار Webhook أن يُجهّز المستخدم مرتين؟
لا. عمليات التسليم المكررة أو المتزامنة تُنفِّذ الفاتورة مرة واحدة فقط، وتقرأ الخدمة الفاتورة من جديد من API SnapEX Pay قبل أي إجراء.
ماذا لو كانت لوحة Marzban متوقفة لحظة وصول الدفعة؟
يُعيد معالج Webhook الرمز 502، فيُعيد SnapEX Pay محاولة التسليم لاحقًا.
لماذا أحتاج إلى HTTPS؟
لا يرسل SnapEX Pay إشعارات Webhook إلا إلى عناوين https://، لذا ضع الخدمة خلف nginx أو Caddy أو Traefik.
هل أنت مستعد لقبول العملات المشفرة؟
أنشئ حساب تاجر، واحصل على مفتاح API، ثم اربط الوحدة. عمولة 1% على كل دفعة، دون رسوم شهرية.