آموزش جامع و گام‌به‌گام حل مشکل درگاه پرداخت در WHMCS

اختلال در درگاه پرداخت، درست مثل این است که درب ورودی فروشگاه شما قفل شده باشد؛ مشتری پشت در می‌ماند و اعتمادش سلب می‌شود. در دنیای هاستینگ، پایداری تراکنش‌ها قلب تپنده کسب‌وکار است. اگر فاکتوری پرداخت شود اما وضعیت آن در سیستم تغییر نکند، تمدید خودکار سرویس متوقف شده و باعث قطع دسترسی کاربر می‌گردد. حتماً زمانی که این مقاله را باز کرده‌اید، با چالش عدم بازگشت کاربر از درگاه یا ثبت نشدن فاکتورها مواجه شده‌اید. نگران نباشید؛ ما اینجا هستیم تا این گره را با هم باز کنیم.

در این مقاله، تمرکز ما بر حل مشکل درگاه پرداخت در WHMCS است. ما از لایه‌های زیرساختی سرور شروع کرده و تا جزئی‌ترین تنظیمات ماژول بانکی پیش می‌رویم تا سیستم مالی شما مجدداً مثل ساعت کار کند.

چک‌لیست 3 مرحله‌ای برای رفع سریع خطای درگاه WHMCS:

• بررسی لاگ سیستم: از منوی Billing به قسمت Gateway Log بروید تا کد خطای ارسالی از سمت بانک را مشاهده کنید.
• تست فایل Callback: مطمئن شوید که آدرس بازگشت درگاه توسط فایروال سرور یا فایل .htaccess مسدود نشده باشد.
• بررسی هماهنگی در پنل وب‌داده: پس از اصلاح درگاه، از بخش «مالی» در پنل کاربری وب‌داده مطمئن شوید که فاکتور مربوطه به وضعیت “پرداخت شده” تغییر یافته است.

مشکل درگاه پرداخت در WHMCS چیست؟

به زبان ساده، اختلال در درگاه زمانی رخ می‌دهد که ارتباط میان اسکریپت WHMCS و API بانک قطع شود؛ یا داده‌های ارسالی از سمت بانک توسط سایت شما پذیرفته نشوند. در نسخه‌های قدیمی WHMCS، به دلیل تفاوت در نسخه‌های PHP و کتابخانه‌های امنیتی، این مشکل بیشتر دیده می‌شود. تصور کنید کاربر مبلغ را پرداخت کرده اما بانک نمی‌تواند به سایت شما بگوید: «پول دریافت شد!». در نتیجه فاکتور “پرداخت نشده” باقی می‌ماند.

نمودار گردش عملیات پرداخت:

    کاربر (سایت) 
➡️ ارسال به درگاه (بانک) 
➡️ پرداخت موفق 
➡️ بازگشت به Callback URL
➡️ تایید تراکنش (WHMCS)
➡️ تغییر وضعیت فاکتور

در هر یک از این مراحل، اگر SSL منقضی شده باشد یا پورت‌های خروجی سرور مسدود باشند، کل زنجیره از هم می‌پاشد.

چرا به رفع اختلالات درگاه نیاز داریم؟

چرا نباید حتی یک ساعت در رفع این مشکل تاخیر کرد؟ پاسخ ساده است: اعتماد مشتری و بقای سرویس. وقتی کاربر برای تمدید سرور مجازی، اختصاصی و یا
سایر سرویس های میزبانی خود اقدام می‌کند، انتظار دارد بلافاصله پس از پرداخت، سرویس او فعال بماند.

• جلوگیری از قطع سرویس: تمدید خودکار سرویس‌ها مستقیماً به وضعیت فاکتور وابسته است.
• کاهش تیکت‌های پشتیبانی: نیمی از تیکت‌های “چرا سرویس من فعال نشد” ناشی از خرابی درگاه است.
• حفظ اعتبار برند: یک درگاه خراب، آماتور بودن شرکت هاستینگ را القا می‌کند.

در سال 2025، با افزایش حملات فیشینگ، کاربران به درگاه‌هایی که خطای SSL می‌دهند یا به درستی ریدایرکت نمی‌شوند، به هیچ وجه اعتماد نمی‌کنند.

پیش‌نیازهای فنی برای پایداری درگاه

قبل از اینکه به سراغ کدها برویم، باید مطمئن شویم که پی ساختمان محکم است. برای رفع مشکل درگاه پرداخت در WHMCS، سرور شما باید شرایط زیر را داشته باشد:

• فعال بودن cURL و OpenSSL: این دو ماژول مسئول ارسال و دریافت ایمن داده‌ها به بانک هستند.
• نسخه PHP سازگار: WHMCS 8.x به PHP 7.2+ نیاز دارد و WHMCS 9.x با PHP 8.1, 8.2, 8.3 کار می‌کند. مطمئن شوید IonCube Loader شما آپدیت باشد.
• گواهینامه SSL معتبر: اکثر بانک‌های نوین (مانند ملت، سامان و زرین‌پال) بدون HTTPS اجازه تراکنش نمی‌دهند.
• اتصال صحیح دیتابیس: جداول tblpaymentgateways (تنظیمات درگاه) و tblpaymethods (روش‌های پرداخت tokenized) نباید خراب (Crash) شده باشند.

آموزش تنظیم Callback در WHMCS و رفع خطاهای بازگشت

در این بخش همراه تیم وب‌داده باشید تا به صورت عملی و تصویری، مشکل عدم تایید تراکنش را حل کنیم. «Callback URL» یا همان آدرس بازگشت، نقطه‌ای است که بانک اطلاعات پرداخت را به آن ارسال می‌کند. اگر این آدرس اشتباه باشد، پول از حساب کاربر کسر می‌شود اما فاکتور شما سبز نمی‌شود.

📝 سناریوی اصلاح درگاه در وب‌داده:

ما برای این آموزش از یک ماژول درگاه مستقیم بانکی استفاده می‌کنیم.

مرحله صفر: ورود به پنل مدیریت WHMCS

ابتدا باید وارد پنل ادمین WHMCS خود شوید:

1. به آدرس https://yourdomain.com/whmcs/admin بروید.
2. نام کاربری و رمز عبور ادمین خود را وارد کنید.
3. پس از ورود، وارد داشبورد مدیریتی می‌شوید.

1- بررسی و تنظیم Gateway Log

اولین قدم، مشاهده لاگ درگاه پرداخت (Gateway Log) است. برای این کار از منوی سمت چپ پنل ادمین به مسیر Billing > Gateway Log بروید. در اینجا پاسخ‌های بانک را می‌بینید.

• ◀️ اگر ستون “Result” مقدار “Error” دارد، کد خطا را بردارید.
• ◀️ مثال: خطای -1 در بانک ملت معمولاً به معنای IP نامعتبر است (آی‌پی سرور شما در لیست سفید بانک نیست).

2- تنظیم دقیق آدرس بازگشت

نحوه دسترسی به تنظیمات Payment Gateways بستگی به نسخه WHMCS شما دارد:

• WHMCS 8.6 و بالاتر: از منوی بالا Addons > Apps & Integrations (یا Configuration > Apps & Integrations)، سپس دسته‌بندی Payments را انتخاب کنید.

• WHMCS 8.0 تا 8.5: روی آیکون چرخ‌دنده (⚙️) کلیک کنید، سپس Configuration > System Settings > Payment Gateways
• WHMCS 7.10 و قدیمی‌تر (شامل نسخه 6): روی آیکون چرخ‌دنده کلیک کنید، سپس Setup > Payments > Payment Gateways

در صفحه Payment Gateways، لیست تمام درگاه‌های فعال و غیرفعال را مشاهده می‌کنید. روی درگاه بانکی خود کلیک کنید تا وارد تنظیمات آن شوید.

مطمئن شوید که آدرس کالبک به درستی وارد شده باشد.

• 🔸 مرحله 1: فایل callback/yourgateway.php را چک کنید که وجود داشته باشد.
• 🔸 مرحله 2: اگر سایت شما با www باز می‌شود، آدرس کالبک هم باید با www باشد. تداخل در این مورد باعث گم شدن نشست (Session) کاربر می‌شود.

مدیریت سرویس و فاکتور در پنل کاربری وب‌داده

اگر شما یکی از کاربران وب‌داده هستید و در هنگام پرداخت با مشکل مواجه شدید، نیازی به نگرانی نیست. ما راهکارهای جایگزینی برای شما پیش‌بینی کرده‌ایم تا سرویس شما هرگز قطع نشود.

• مشاهده فاکتورها در بخش مالی وب‌داده: با ورود به پنل، می‌توانید لیست تمام پرداخت‌های موفق و ناموفق را ببینید.
• تمدید خودکار سرویس در پنل وب‌داده: اگر درگاه مستقیم با خطا مواجه شد، بهترین راهکار افزایش موجودی کیف پول است. با این کار، سیستم به صورت خودکار مبلغ فاکتور را از اعتبار شما کسر کرده و سرویس را در لیست «سرویس‌های من» فعال نگه می‌دارد.

روش پرداخت	سرعت تایید	پایداری	امنیت
درگاه مستقیم بانکی	آنی	متوسط (بستگی به بانک)	بسیار بالا
کیف پول (اعتبار)	آنی	100٪ (توصیه شده)	بسیار بالا
کارت به کارت	دستی	بالا	متوسط

نکات امنیتی و جلوگیری از تراکنش‌های جعلی

امنیت درگاه فقط به معنای کار کردن آن نیست؛ بلکه به معنای “درست” کار کردن آن است.

• تست Sandbox: همیشه قبل از عملیاتی کردن درگاه، یک تراکنش 1000 تومانی واقعی انجام دهید.
• بررسی مبلغ تراکنش: مطمئن شوید ماژول درگاه، مبلغ بازگشتی از بانک را با مبلغ فاکتور در WHMCS مقایسه می‌کند (تا کسی نتواند با پرداخت 1 تومان، فاکتور 1 میلیونی را پاس کند!).
• محدودیت IP: در صورت امکان، دسترسی به فایل‌های کالبک را فقط برای رنج آی‌پی‌های بانک محدود کنید.
• استفاده از HMAC Signature: برای امنیت بیشتر، callback را با HMAC امضا کنید تا از صحت داده‌های دریافتی اطمینان حاصل شود.

خدمات WHMCS در وب‌داده؛ تضمین پایداری مالی

ما در وب‌داده، فراتر از ارائه سرور، در کنار شما هستیم تا کسب‌وکارتان بدون وقفه رشد کند. تیم فنی ما با تجربه عیب‌یابی هزاران درگاه پرداخت، بهترین زیرساخت را برای سیستم‌های مالی فراهم کرده است.

✅ مزایای استفاده از سرویس‌های وب‌داده:

• سرورهای بهینه شده برای اجرای بی نقص WHMCS نسخه‌های 8.x و 9.x
• مانیتورینگ 24 ساعته پورت‌های بانکی
• ارائه گواهینامه SSL رایگان برای امنیت درگاه‌های شما

نتیجه‌گیری: راهنمای حل مشکل درگاه پرداخت در WHMCS

در این راهنما، مسیر کامل رفع مشکل درگاه پرداخت در WHMCS را بررسی کردیم. از اهمیت حیاتی Gateway Log گفتیم و آموختیم که چگونه تنظیمات اشتباه Callback می‌تواند باعث سردرگمی کاربران شود. به یاد داشته باشید که تکنولوژی همیشه در حال تغییر است و آپدیت نگه داشتن ماژول‌ها و نسخه WHMCS در سال‌های ۲۰۲۴ تا ۲۰۲۶، یک ضرورت است، نه یک انتخاب.

اگر همچنان با مشکل مواجه هستید، پیشنهاد می‌کنیم وضعیت سرور خود را در پنل وب‌داده بررسی کنید یا از طریق بخش تیکت با کارشناسان ما در ارتباط باشید. هدف ما این است که شما بدون دغدغه فنی، فقط به فکر توسعه تجارت خود باشید.

امیدوارم این مقاله از بلاگ وب‌داده برای شما مفید بوده باشد. در صورتی که سوالی داشتید می‌توانید در بخش نظرات با ما در ارتباط باشید. 😉🚀

سوالات متداول از حل مشکل درگاه پرداخت در WHMCS