Xboard و V2Board پنل‌های محبوبی برای فروش اشتراک VPN و پروکسی هستند. به‌طور پیش‌فرض مشتری با کارت یا از طریق درگاهی که خودتان میزبانی می‌کنید پرداخت می‌کند. این راهنما نشان می‌دهد چطور کریپتو اضافه کنید: مشتری با USDT روی شبکه‌های TRC20، ERC20 یا BEP20 یا با کوین دیگری پرداخت می‌کند و پنل خودش سفارش را باز می‌کند. به کیف پول، نود یا درگاه خودمیزبان نیازی نیست: پول به موجودی فروشنده شما در SnapEX Pay می‌رسد.
پرداخت چطور انجام می‌شود
customer → panel checkout → SnapEX Pay page
SnapEX Pay → signed webhook → panel
plugin → GET invoice from the API → paid?
panel → order opened
- هنگام پرداخت، افزونه برای سفارش یک فاکتور SnapEX Pay می‌سازد (
trade_noپنل همانexternal_idفاکتور است) و مشتری را به صفحه پرداخت می‌فرستد. - مشتری کوین را انتخاب و پرداخت می‌کند. وقتی فاکتور پرداخت شد، SnapEX Pay یک وب‌هوک امضاشده به پنل می‌فرستد.
- افزونه امضا را بررسی می‌کند، فاکتور را از API SnapEX Pay می‌پرسد و فقط اگر وضعیت آنجا
paidباشد سفارش را پرداخت‌شده علامت می‌زند.
چه چیزهایی لازم است
- Xboard با سیستم افزونه (PHP 8.2 یا جدیدتر)، یا V2Board / نسخه قدیمی Xboard که درگاه‌ها را از
app/Paymentsبارگذاری می‌کند (PHP 7.3 یا جدیدتر). - افزونه cURL در PHP.
- دسترسی به پنل از اینترنت با HTTPS: SnapEX Pay وب‌هوک را فقط به آدرس‌های عمومی HTTPS می‌فرستد.
- حساب فروشنده SnapEX Pay: ثبت‌نام در pay.snapex.pro.
گام ۱. نصب افزونه
فایل snapexpay-xboard-1.2.0.zip را دانلود کنید (مجوز MIT، رایگان).
Xboard. پنل مدیریت ← Plugins ← آپلود ZIP ← Install ← Enable برای «SnapEX Pay». یا فایل را در پوشه پنل باز کنید:
cd /path/to/Xboard
curl -fsSLO https://pay.snapex.pro/downloads/xboard/snapexpay-xboard-1.2.0.zip
unzip snapexpay-xboard-1.2.0.zip
mv snapexpay-xboard-1.2.0 plugins/Snapexpay
نام پوشه باید دقیقاً plugins/Snapexpay باشد؛ در لینوکس بزرگی و کوچکی حروف مهم است. سپس Plugins ← Install ← Enable.
V2Board و Xboard قدیمی. فقط یک فایل از آرشیو را در پنل کپی کنید:
unzip -p snapexpay-xboard-1.2.0.zip \
snapexpay-xboard-1.2.0/app/Payments/SnapexPay.php \
> /path/to/v2board/app/Payments/SnapexPay.php
اگر از OPcache یا Octane استفاده می‌کنید، PHP-FPM یا Octane را ری‌استارت کنید. بررسی کنید که آدرس سایت (app_url) در تنظیمات V2Board پر شده باشد: بدون آن افزونه نمی‌تواند مشتری را پس از پرداخت به صفحه سفارش برگرداند.
گام ۲. دریافت کلید API
در پنل فروشنده SnapEX Pay صفحه Developers را باز کنید و یک کلید API صادر کنید. کلید فقط یک بار نمایش داده می‌شود؛ همان لحظه کپی‌اش کنید. کلیدی که در پنل صادر می‌شود همه دسترسی‌های Merchant API را دارد، از جمله invoices.read و invoices.write که افزونه لازم دارد. صدور دوباره کلید، کلید قبلی را فوراً باطل می‌کند؛ پس همان لحظه آن را در پنل هم عوض کنید.
گام ۳. افزودن روش پرداخت
پنل مدیریت ← Payment configuration ← Add payment method ← درگاه SnapexPay. فیلدها:
- API key: کلید گام ۲.
- Webhook secret: در گام ۴ پر می‌شود.
- Network fee paid by:
merchant(پیش‌فرض)، مشتری دقیقاً مبلغ سفارش را می‌پردازد؛customer، کارمزد شبکه روی مبلغ اضافه می‌شود. بیشتر: کارمزد فاکتور کریپتو را چه کسی می‌پردازد. - Payment window, minutes: چند دقیقه فاکتور قابل پرداخت است. Xboard: پیش‌فرض ۶۰، حداکثر ۱۲۰؛ V2Board: پیش‌فرض ۲۰، حداکثر ۳۰. این سقف کمتر از مهلت خود پنل برای سفارش‌های پرداخت‌نشده است تا مشتری نتواند سفارشی را که پنل لغو کرده بپردازد.
- USD per 1 shop currency: اگر قیمت‌ها به دلار است،
1. پنل‌ها مبلغ را به سنت نگه می‌دارند و افزونهtotal / 100 × usd_rateرا می‌فرستد. برای فروشگاهی با CNY حدود0.14است. این نرخ ثابت است: وقتی نرخ ارز تغییر کرد، خودتان آن را به‌روز کنید. - Environment:
liveیاtest(گام ۵). - Partner ID: اگر خودتان راه‌اندازی می‌کنید خالی بگذارید؛ یکپارچه‌سازی که شما را وصل کرده، شناسه خود را اینجا می‌گذارد.
- API URL: مقدار پیش‌فرض
https://snapex.pro/api/v1/merchantرا نگه دارید.
حداقل مبلغ فاکتور 0.50 USD است: سفارشی که پس از تبدیل کمتر از این باشد، هنگام پرداخت خطا می‌دهد.
گام ۴. تنظیم وب‌هوک
هر روش پرداخت در پنل، آدرس notify مخصوص خودش را دارد:
https://your-panel.example/api/v1/guest/payment/notify/SnapexPay/{uuid}
Xboard آدرس کامل را در فهرست روش‌های پرداخت نشان می‌دهد. در پنل فروشنده، در صفحه Developers، آن را به‌عنوان آدرس وب‌هوک وارد و ذخیره کنید. رمز امضای whsec_… فقط یک بار، درست پس از اولین ذخیره، نمایش داده می‌شود؛ آن را در Webhook secret روش پرداخت کپی کنید.
در پنل فروشنده برای هر حساب یک آدرس وب‌هوک وجود دارد و همه رویدادها به آن می‌رسند. افزونه فقط با فاکتور پرداخت‌شده سفارش را باز می‌کند؛ برای رویدادهای دیگر پنل خطا برمی‌گرداند (422 در Xboard، 500 در V2Board). در گزارش ارسال‌ها این به شکل ارسال ناموفق دیده می‌شود و طبیعی است.
افزونه اعلان را این‌طور بررسی می‌کند:
- هدر
Webhook-Signature: HMAC-SHA256 از{Webhook-Timestamp}.{raw body}با رمز شما؛ - اختلاف
Webhook-Timestampبا ساعت سرور حداکثر ۵ دقیقه؛ NTP را روشن نگه دارید؛ - خود فاکتور که با کلید شما دوباره از API SnapEX Pay خوانده می‌شود: سفارش فقط وقتی پرداخت‌شده می‌شود که وضعیت آنجا
paidباشد.
درباره امضا و تلاش‌های دوباره: وب‌هوک پرداخت کریپتو.
گام ۵. سفارش تست بدون پول واقعی
- Environment را روی
testبگذارید و ذخیره کنید. - در پنل یک سفارش بسازید و به پرداخت بروید.
- صفحه SnapEX Pay برچسب Test دارد. هر کوین و شبکه‌ای را انتخاب کنید: صفحه یک آدرس تست نشان می‌دهد و حدود ۱۰ ثانیه بعد پرداخت خودبه‌خود تأیید می‌شود. لازم نیست چیزی بفرستید.
- سفارش باید ظرف چند ثانیه پرداخت‌شده شود. اگر نشد، گزارش ارسال‌ها در صفحه Developers و لاگ پنل (
storage/logs) را ببینید. - Environment را به
liveبرگردانید.
تا وقتی روش پرداخت روی test است، هر سفارشی که با آن پرداخت شود بدون پول باز می‌شود؛ پس تست را کوتاه نگه دارید. وقتی روش دوباره روی live باشد، افزونه فاکتورهای تست را رد می‌کند و پرداخت تست نمی‌تواند سفارش واقعی را باز کند. بیشتر: چگونه پرداخت کریپتو را بدون پول واقعی تست کنیم.
مشتری چه می‌بیند
صفحه SnapEX Pay با انتخاب کوین: USDT روی TRC20، ERC20 و BEP20 و کوین‌های دیگر (در مجموع بیش از ۵۰) وقتی SnapEX Pay آن‌ها را برای مبلغ فاکتور ارائه می‌دهد. اگر مشتری دوباره «پرداخت» را بزند، تا وقتی فاکتور معتبر است همان فاکتور باز می‌شود؛ اگر منقضی شده باشد، برای همان سفارش فاکتور تازه‌ای ساخته می‌شود (external_id به شکل {trade_no}-1، -2 و غیره).
اگر مشتری کمتر از مبلغ بفرستد، سفارش باز نمی‌شود: مبلغ دریافت‌شده به موجودی SnapEX Pay شما می‌رسد و باقی را خودتان با مشتری حل می‌کنید. کم‌پرداخت چطور کار می‌کند: مشتری کمتر از مبلغ فاکتور فرستاد.
اگر چیزی کار نکرد
- SnapexPay در فهرست درگاه‌ها نیست (Xboard). پوشه باید دقیقاً
plugins/Snapexpayباشد و افزونه هم نصب و هم فعال شده باشد. - هنگام پرداخت «A valid merchant API key is required» یا «This source IP is not allowed». کلید اشتباه یا باطل است، یا فهرست IPهای مجاز کلید شامل IP خروجی سرور پنل نیست.
- «Amount is below the … USD minimum». سفارش پس از تبدیل کمتر از 0.50 USD است؛ USD per 1 shop currency را بررسی کنید.
- مشتری پرداخت کرده اما سفارش پرداخت‌نشده مانده. گزارش ارسال‌ها را در پنل فروشنده ببینید. معمولاً Webhook secret مطابقت ندارد، ساعت سرور بیش از ۵ دقیقه جلو یا عقب است، آدرس به UUID روش دیگری اشاره می‌کند، پروکسی معکوس بدنه درخواست را تغییر می‌دهد یا پنل به API SnapEX Pay دسترسی ندارد. ارسال ناموفق را می‌توان از همان گزارش دوباره فرستاد.
هزینه
۱٪ برای هر پرداخت، بدون هزینه راه‌اندازی و بدون هزینه ماهانه. افزونه رایگان است.
صفحه افزونه: Xboard / V2Board. مرور برای سرویس‌های VPN: پرداخت کریپتو برای VPN. ثبت‌نام: pay.snapex.pro.