وقتی درگاه پرداخت ووکامرس از کار می‌افتد، مشتری نمی‌تواند پول بدهد و فروشنده در همان ساعت اوج، پشت سر هم تماس‌های نگران‌کننده می‌گیرد. برخلاف بسیاری از خطاهای ووکامرس که با پیام واضح همراهند، خطای درگاه پرداخت معمولاً بی‌صدا رخ می‌دهد: صفحه باز نمی‌شود، یا باز می‌شود اما تراکنش تأیید نمی‌شود، یا پول کم می‌شود اما سفارش ثبت نمی‌گردد. در این مقاله، همان مسیری را طی می‌کنم که در پروژه‌های واقعی فروشگاهی برای ردیابی خطای درگاه پرداخت استفاده کرده‌ام — از معماری کلاس WC_Payment_Gateway تا لایه‌های پنهانی که معمولاً نادیده گرفته می‌شوند.

معماری درگاه پرداخت در ووکامرس از دید مهندسی

درگاه پرداخت در ووکامرس یک افزونه جدا نیست؛ یک کلاس پیاده‌سازی‌شده روی قرارداد WC_Payment_Gateway است. هر درگاه — چه درگاه‌های بین‌المللی مثل Stripe و PayPal، چه درگاه‌های ایرانی مثل زرین‌پال، آیدی‌پی و پی‌پینگ — این کلاس را گسترش می‌دهد و سه متد کلیدی را پیاده می‌کند: process_payment() که تراکنش را آغاز می‌کند، callback_handler() که پاسخ سرور بانک را دریافت می‌کند، و is_available() که تعیین می‌کند آیا درگاه در شرایط فعلی قابل استفاده است یا نه.

زنجیره اجرایی پرداخت در ووکامرس به این شکل است: مشتری روی دکمه «ثبت سفارش» می‌زند، ووکامرس متد process_payment() را صدا می‌زند، درگاه یک درخواست به API بانک ارسال می‌کند، پاسخ API دریافت می‌شود و در صورت موفقیت، کاربر به صفحه درگاه هدایت می‌شود. بعد از تأیید مشتری در صفحه بانک، سرور بانک به سایت شما بازمی‌گردد و درگاه متد callback_handler() را اجرا می‌کند تا تراکنش را verify کند و سفارش را ثبت نماید. اگر هر حلقه از این زنجیره بشکند، تجربه کاربری به «درگاه کار نمی‌کند» تبدیل می‌شود، در حالی که ریشه در همان حلقه شکسته است.

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

تفکیک چهار لایه‌ای که باید بشناسید

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

  • لایه پیکربندی: کلید API، مرچنت، تنظیمات امنیتی و فعال‌سازی درگاه اشتباه است.
  • لایه انتقال: درخواست خروجی به بانک به دلیل فایروال، cURL یا DNS ناموفق است.
  • لایه بازگشت: callback یا verify به‌دلیل SSL، URL یا پاسخ نامعتبر شکست می‌خورد.
  • لایه محیط: کش، نشست، تضاد افزونه یا منابع سرور، اجرای پرداخت را قطع می‌کند.

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

سیمپتوملایه احتمالیاولین اقدام تشخیصی
درگاه از فهرست پرداخت غایب استلایه پیکربندیبررسی فعال‌سازی و شرایط is_available()
درگاه باز نمی‌شود یا خطای انتقال می‌دهدلایه انتقالبررسی cURL، DNS و لاگ درگاه
پول کم می‌شود اما سفارش ثبت نمی‌شودلایه بازگشتبررسی callback URL و لاگ verify
خطا فقط برای بعضی کاربران رخ می‌دهدلایه محیطبررسی کش، نشست و کوکی

فعال‌سازی، وضعیت و پیکربندی اولیه درگاه

قبل از هر عیب‌یابی عمیق، باید مطمئن شوید درگاه به‌درستی فعال شده است. ووکامرس هر درگاه را با دو پارامتر کنترل می‌کند: enabled که وضعیت فعال/غیرفعال را تعیین می‌کند، و test_mode که حالت تست یا تولید را مشخص می‌کند. اگر درگاه در حالت تست باشد، تراکنش‌ها به‌صورت آزمایشی پردازش می‌شوند و مبلغی از حساب مشتری کم نمی‌شود. این سناریو بارها به‌عنوان «درگاه کار نمی‌کند» گزارش شده در حالی که درگاه سالم بوده و ادمین فراموش کرده حالت تست را به تولید تغییر دهد.

سه اشتباه رایج در این لایه:

  1. فعال‌سازی سطحی بدون ذخیره تنظیمات: گاهی ادمین تیک «فعال» را می‌زند اما ذخیره نمی‌کند. در نسخه‌های قدیمی ووکامرس، این اتفاق شایع بود و درگاه به‌نظر فعال می‌رسید اما در حقیقت غیرفعال بود.
  2. حالت تست روی سایت زنده: اگر حالت تست فعال باشد، مشتری به صفحه تست بانک هدایت می‌شود و در انتها بازمی‌گردد اما تراکنش واقعی ثبت نمی‌شود. این سناریو در فروشگاه‌های تازه راه‌اندازی‌شده شایع است.
  3. ترتیب درگاه‌ها: ووکامرس درگاه‌ها را به ترتیب نمایش می‌دهد و در بعضی تنظیمات، ترتیب اشتباه باعث می‌شود درگاه مورد نظر در پایان فهرست مخفی شود. برای فروشگاه‌های چنددرگاهی، ترتیب را در تنظیم روش‌های پرداخت در ووکامرس تنظیم کنید.

روش تشخیص سریع: در پیشخوان ووکامرس، بخش «تنظیمات → پرداخت‌ها»، همه درگاه‌ها را ببینید. اگر درگاه مورد نظر در فهرست نیست یا در وضعیت غیرفعال است، همان لحظه رفع کنید. راهنمای کلی در اتصال ووکامرس به درگاه‌های پرداخت آمده است.

شرط is_available و رفتار پنهان درگاه

متد is_available() در هر درگاه، تصمیم نهایی را می‌گیرد که درگاه در فهرست پرداخت‌ها ظاهر شود یا نه. این متد معمولاً چند شرط را بررسی می‌کند: فعال بودن درگاه، وجود کلید API معتبر، اجازه بر اساس کشور، و توانایی پردازش مبلغ فعلی. اگر هر شرط fail شود، درگاه بی‌صدا از فهرست حذف می‌شود — بدون پیام خطا برای ادمین. این دقیقاً همان سناریویی است که در ظاهر «درگاه کار نمی‌کند» به نظر می‌رسد، در حالی که درگاه خودش را از فهرست حذف کرده است.

کلیدهای API، مرچنت و اعتبارسنجی سرور

درگاه‌های پرداخت برای احراز هویت، از کلیدهای API استفاده می‌کنند. درگاه‌های بین‌المللی مثل Stripe، از جفت کلید publishable key و secret key استفاده می‌کنند. درگاه‌های ایرانی، معمولاً از یک merchant_id یا terminal_id به‌همراه یک password یا token استفاده می‌کنند. هرگونه اختلاف در این مقادیر — حتی یک فاصله پنهان یا یک کاراکتر اشتباه — منجر به شکست احراز هویت و در نتیجه خطای درگاه می‌شود.

سه اشتباه دقیق در این لایه:

  1. کپی‌پیست با فاصله اضافه: بعضی کلیدها با یک فاصله اضافه در انتها کپی می‌شوند که در ظاهر دیده نمی‌شود. پیش از ذخیره، مقدار کلید را در یک ویرایشگر متن ساده پاک‌سازی کنید.
  2. کلید تست به‌جای کلید تولید: اگر ادمین کلید تست را در حالت تولید استفاده کند، درگاه درخواست را رد می‌کند. همیشه مطمئن شوید کلید با حالت فعال درگاه سازگار است.
  3. عدم تطابق مرچنت با کلید: اگر کلید از یک حساب بانکی و مرچنت از حساب دیگر باشد، درگاه درخواست را رد می‌کند اما پیام خطای دقیق نمی‌دهد. راه تشخیص: در پنل بانک، آخرین تراکنش‌ها را ببینید؛ اگر هیچ درخواستی ثبت نشده، ریشه در کلید است.

برای درک دقیق فرآیند اتصال و ترتیب احراز هویت، اتصال درگاه پرداخت به ووکامرس مسیر گام‌به‌گام را نشان می‌دهد. اصول کلی امنیت API را هم در امنیت فروشگاه ووکامرس آورده‌ام.

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

مرحله request: باز نشدن درگاه یا خطای انتقال

وقتی مشتری روی دکمه پرداخت می‌زند و ووکامرس متد process_payment() را صدا می‌زند، درگاه یک درخواست HTTP به API بانک ارسال می‌کند. این درخواست معمولاً از طریق cURL یا WP HTTP API انجام می‌شود. اگر این درخواست به هر دلیل fail شود، مشتری به صفحه بانک نمی‌رسد و در نهایت به سایت بازمی‌گردد با پیام «خطای پرداخت» یا بدون پیام.

سه علت رایج در این لایه:

  • مسدودسازی خروجی توسط فایروال سرور: بعضی هاست‌های اشتراکی، درخواست‌های خروجی به دامنه‌های خارجی را مسدود می‌کنند. اگر بانک شما روی یک دامنه خارجی باشد، درخواست هرگز ارسال نمی‌شود. راه تشخیص: از داخل سرور، با ابزار curl به API بانک درخواست بزنید؛ اگر پاسخ نداد، ریشه در فایروال است. مثال دستور را می‌توانید در دستورات ضروری CLI برای مدیریت سرور ببینید.
  • مشکل DNS یا SSL در سطح سرور: اگر سرور شما نتواند دامنه بانک را resolve کند یا گواهی SSL بانک را تأیید نکند، درخواست شکست می‌خورد. این سناریو در سرورهای با پیکربندی نامتعارف شایع است.
  • Timeout در پاسخ بانک: اگر بانک کند پاسخ دهد و مدت انتظار از default_socket_timeout بیشتر شود، درخواست قطع می‌شود. رفع این سناریو در رفع خطای Maximum execution time آمده است.

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

مرحله callback و verify: قلب تراکنش

پس از تأیید مشتری در صفحه بانک، سرور بانک به سایت شما بازمی‌گردد. این بازگشت، معمولاً در یک URL مشخص اتفاق می‌افتد که در پنل درگاه تنظیم شده است. سپس درگاه ووکامرس متد callback_handler() را اجرا می‌کند تا تراکنش را verify کند و سفارش را به وضعیت processing ببرد. اگر این مرحله به هر دلیل شکست بخورد، پول از حساب مشتری کم شده اما سفارش نهایی نمی‌شود. این سناریو در بازار ایران شایع‌ترین شکل خطای درگاه است.

سه علت دقیق در این لایه:

  1. URL بازگشت اشتباه: اگر URL بازگشت در پنل بانک با آنچه در افزونه تنظیم شده مطابقت نداشته باشد، بانک به مسیر اشتباهی هدایت می‌کند و اطلاعات سفارش گم می‌شود. همیشه مقدار URL را در دو طرف تطبیق دهید.
  2. شکست در مرحله verify: بعضی درگاه‌های ایرانی دو مرحله‌ای هستند: request و verify. اگر مرحله دوم به هر دلیل (پاسخ نامعتبر، قطع اتصال، خطای امضا) شکست بخورد، پول کم می‌شود اما سفارش ثبت نمی‌شود. راه تشخیص: لاگ دقیق درگاه را ببینید.
  3. قطع نشست کاربر: اگر نشست ووکامرس منقضی شود، verify نمی‌تواند سفارش را به کاربر جاری متصل کند. نانس معتبر در این مرحله ضروری است.

روش تشخیص: در پیشخوان ووکامرس، بخش «وضعیت سیستم» و لاگ درگاه. اگر ردیفی وجود دارد که در آن verify اجرا شده اما پاسخ خطا داشته، ریشه تأییدشده است. سناریوی مشابه در رفع خطای پرداخت در ووکامرس و خطای درگاه پرداخت ووکامرس مفصل‌تر آمده است.

SSL، HTTPS و الزامات امنیتی درگاه‌ها

اکثر درگاه‌های پرداخت مدرن — چه بین‌المللی و چه ایرانی — اجازه بازگشت به یک URL غیر HTTPS را نمی‌دهند. اگر سایت شما روی HTTP باشد یا گواهی SSL آن معتبر نباشد، درگاه درخواست را رد می‌کند یا مشتری را در میانه فرآیند قطع می‌کند. سه سناریو دقیق:

  • سایت روی HTTP: درگاه‌های پرداخت بدون استثنا، بازگشت به HTTP را رد می‌کنند. راه‌حل: نصب و فعال‌سازی SSL. مسیر کامل در نصب SSL و فعال‌سازی HTTPS آمده است.
  • گواهی منقضی: اگر گواهی SSL منقضی شده باشد، درگاه در بازگشت خطا می‌دهد. بررسی دوره‌ای این تاریخ، یکی از کارهای نگهداری فروشگاه است.
  • گواهی Self-signed: اگر گواهی توسط مرجع معتبر امضا نشده باشد، بعضی درگاه‌ها آن را رد می‌کنند. همیشه از گواهی معتبر استفاده کنید.

روش تشخیص سریع: در مرورگر، روی قفل آدرس کلیک کنید. اگر «Not Secure» یا خطای گواهی می‌بینید، اول این را رفع کنید. تأثیر HTTPS بر سئو و اعتماد کاربر را در تأثیر HTTPS بر سئو آورده‌ام.

فایروال، WAF و مسدودسازی IP سرور

لایه‌ای که بیشترین سردرگمی را می‌سازد: فایروال. هم فایروال سمت سرور شما و هم فایروال سمت درگاه بانک می‌توانند درخواست‌های پرداخت را بلاک کنند. در سمت سرور شما، بعضی افزونه‌های امنیتی، درخواست‌های خروجی به API بانک یا درخواست‌های ورودی callback را به‌عنوان «مشکوک» علامت می‌زنند و بلاک می‌کنند. در سمت بانک، بعضی IPهای سرور شما در لیست سیاه قرار می‌گیرند.

سه سناریوی دقیق:

  1. افزونه امنیتی، callback را بلاک می‌کند: اگر درخواست بازگشت از بانک با IP خارجی وارد سایت شود و افزونه امنیتی، IP بانک را به‌عنوان «مهاجم» علامت بزند، callback رد می‌شود. راه‌حل: IP بانک را در لیست سفید افزونه امنیتی قرار دهید.
  2. فایروال سرور، خروجی به بانک را بلاک می‌کند: بعضی هاست‌ها، درخواست‌های خروجی به دامنه‌های خاص را محدود می‌کنند. راه تشخیص: از داخل سرور تست cURL بگیرید.
  3. IP سرور شما در لیست سیاه بانک: اگر سرور شما روی یک IP اشتراکی آلوده میزبانی می‌شود، ممکن است بانک آن را بلاک کرده باشد. تماس با پشتیبانی بانک و درخواست بررسی لازم است.

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

تنظیمات سرور: PHP، cURL، timeout و منابع

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

  • افزونه‌های PHP (cURL، OpenSSL، mbstring): اگر افزونه PHP در سرور نصب نباشد یا نسخه قدیمی باشد، درگاه نمی‌تواند با API بانک ارتباط برقرار کند. این سناریو در هاست‌های اشتراکی کم‌کیفیت شایع است.
  • max_execution_time: اگر این مقدار پایین باشد و بانک کند پاسخ دهد، درخواست قطع می‌شود. مقدار امن برای فروشگاه: حداقل ۱۲۰ ثانیه. رفع خطا در رفع خطای Maximum execution time در PHP آمده است.
  • memory_limit: اگر این مقدار پایین باشد، در فرآیند پردازش پرداخت، سرور به‌دلیل کمبود حافظه fail می‌شود. رفع در خطای حافظه در وردپرس.

روش تشخیص: در پیشخوان ووکامرس، بخش «وضعیت سیستم»، همه پارامترهای PHP را ببینید. اگر هر کدام از آن‌ها در حالت هشدار بود، همان لحظه رفع کنید. مشخصات سرور مورد نیاز وردپرس را در سرور وردپرس چه مشخصاتی باید داشته باشد آورده‌ام.

کش، نشست و کوکی؛ سه گلوگاه نامرئی

لایه‌ای که بیشترین سردرگمی را می‌سازد: کش و نشست. فرآیند پرداخت در ووکامرس، یک فرآیند stateful است — یعنی هر کاربر در طول فرآیند، یک نشست منحصربه‌فرد دارد که در آن اطلاعات سفارش، کلید تراکنش و نانس‌ها ذخیره می‌شود. اگر کش صفحه‌ای مثل /checkout به‌اشتباه عمومی کش شود، هر کاربر نسخه‌ای می‌بیند که برای کاربر دیگری ساخته شده، و در نهایت تراکنش با اشتباه مواجه می‌شود.

سه سناریوی دقیق در این لایه:

  • کش صفحه پرداخت: صفحه /checkout باید همیشه از کش استثنا باشد. اصول کش در ووکامرس را در بهترین افزونه‌های کش وردپرس و تنظیمات دقیق را در پیکربندی افزونه کش آورده‌ام.
  • CDN حذف کوکی نشست: بعضی CDNها، کوکی‌های نشست ووکامرس را کش می‌کنند یا حذف می‌کنند. نتیجه: نشست کاربر در حین پرداخت از دست می‌رود.
  • افزونه‌های session اختصاصی: بعضی افزونه‌های cache و session، با نشست پیش‌فرض ووکامرس تداخل می‌کنند و نانس را باطل می‌کنند.

روش تشخیص قطعی: در پنجره ناشناس (Incognito) بدون کش، تست کنید. اگر پرداخت درست انجام شد، ریشه در لایه کش است.

در فرآیند پرداخت، نشست کاربر به‌اندازه‌ی کلید API اهمیت دارد. اگر نشست بشکند، بانک پول را می‌گیرد اما سایت نمی‌داند پول به کدام سفارش وصل شود.

تضاد افزونه و قالب با لایه پرداخت

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

  1. افزونه‌های چندگانه درگاه: نصب همزمان چند افزونه پرداخت که هرکدام کلاس WC_Payment_Gateway را ثبت می‌کنند، می‌تواند باعث تضاد در ثبت گیت‌وی‌ها و در نتیجه حذف یا مخفی شدن درگاه شود. یک درگاه، یک افزونه.
  2. افزونه‌های تخفیف و اعمال قانون: بعضی افزونه‌های تخفیف یا قیمت‌گذاری پویا، در لحظه محاسبه مبلغ نهایی، ترتیب را تغییر می‌دهند و مبلغ ارسالی به بانک با مبلغ نمایش‌داده‌شده متفاوت می‌شود؛ در نتیجه بانک تراکنش را رد می‌کند.
  3. قالب سفارشی صفحه پرداخت: اگر قالب، ساختار صفحه پرداخت را با دامنه خودش بازنویسی کند، درگاه ممکن است دکمه پرداخت یا فیلدهای لازم را پیدا نکند.

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

درگاه‌های ایرانی: نکات اختصاصی و تفاوت‌های میدانی

درگاه‌های ایرانی در چند نکته با درگاه‌های بین‌المللی تفاوت ساختاری دارند که در عیب‌یابی اهمیت جدی دارند:

  • الزام IP اختصاصی: بعضی درگاه‌های ایرانی فقط درخواست‌های ارسال‌شده از یک IP مشخص را می‌پذیرند. اگر IP سرور شما تغییر کند، درگاه تراکنش را رد می‌کند.
  • محدودیت مبلغ: بعضی درگاه‌ها برای مبالغ بالای یک آستانه، الزام به تنظیمات خاص دارند. اگر مبلغ سبد از این آستانه بالاتر باشد، تراکنش رد می‌شود.
  • تفاوت API در نسخه‌های مختلف: API درگاه‌های ایرانی گاهی تغییر می‌کند و افزونه‌های قدیمی به‌روز نمی‌شوند. اگر تراکنش‌های شما بی‌دلیل شکست می‌خورد، بررسی سازگاری نسخه افزونه با نسخه جدید API ضروری است.
  • الزام نماد اعتماد: بعضی درگاه‌ها فقط در دامنه‌هایی که نماد اعتماد دارند فعال می‌شوند. اگر دامنه شما در فهرست نیست، تراکنش رد می‌شود.

در تجربه من، اکثر خطاهای درگاه‌های ایرانی به‌جای ریشه فنی، ریشه پیکربندی دارند: کلید API قدیمی، URL بازگشت اشتباه یا عدم تطابق IP. سند دقیق اتصال در اتصال ووکامرس به درگاه‌های پرداخت آمده است.

هوک‌های پرداخت و ترتیب اجرا

در لایه کد، پرداخت ووکامرس با چند هوک کلیدی مدیریت می‌شود. اگر با کد سفارشی کار می‌کنید، شناختن این هوک‌ها ضروری است:

  1. woocommerce_checkout_order_processed: بعد از پردازش سفارش و قبل از انتقال به درگاه.
  2. woocommerce_payment_complete: بعد از تأیید پرداخت موفق، پیش از تغییر وضعیت به processing.
  3. woocommerce_order_status_changed: در هر تغییر وضعیت سفارش، از جمله بعد از پرداخت.
  4. woocommerce_thankyou: بعد از بازگشت موفق از درگاه، در صفحه تشکر.

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

لاگ‌گیری و ردیابی در لایه داده

لاگ‌گیری، اولین قدم برای هر عیب‌یابی جدی در لایه پرداخت است. ووکامرس دو لاگ اصلی دارد: لاگ عمومی رویدادها در wp-content/uploads/wc-logs/، و لاگ اختصاصی درگاه که توسط افزونه درگاه تولید می‌شود. همچنین لاگ PHP در debug.log می‌تواند خطاهای سطح پایین را نشان دهد.

سه نکته دقیق در این لایه:

  1. فعال‌سازی WP_DEBUG_LOG: در محیط استجینگ فعال کنید تا خطاهای PHP بدون نمایش به کاربر، در فایل ذخیره شوند. روش دقیق در پیدا کردن خطاهای ووکامرس در لاگ‌ها آمده است.
  2. ذخیره لاگ درگاه: بعضی افزونه‌های درگاه، لاگ دقیق درخواست و پاسخ را ذخیره می‌کنند. اگر این لاگ خاموش باشد، عیب‌یابی تقریباً غیرممکن می‌شود.
  3. پایش دوره‌ای: لاگ را نباید فقط در زمان مشکل خواند. یک بازبینی هفتگی می‌تواند نشان دهد نرخ خطای درگاه به‌آرامی در حال افزایش است.

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

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

پروتکل عیب‌یابی گام‌به‌گام

حالا ترتیب عملی عیب‌یابی، از سریع‌ترین به دقیق‌ترین:

  1. بازتولید روی استجینگ: قبل از هر چیز، خطا را در محیطی جدا از سایت زنده بازتولید کنید. روش راه‌اندازی در بکاپ گرفتن از فروشگاه ووکامرس آمده است.
  2. بررسی وضعیت سیستم ووکامرس: در WooCommerce → Status، همه شاخص‌های سلامت را ببینید.
  3. بررسی فعال‌سازی و کلید API: از فعال بودن درگاه و صحت کلید مطمئن شوید.
  4. کنسول مرورگر: تب Console و Network را باز کنید و درخواست‌های مربوط به پرداخت را بررسی کنید.
  5. تست cURL از سرور: با دستور curl به API بانک درخواست بزنید. اگر پاسخ نداد، ریشه در لایه سرور است.
  6. بررسی لاگ درگاه و ووکامرس: آخرین ردیف‌های لاگ را در لحظه خطا ببینید.
  7. پاک کردن کامل کش: کش افزونه، آبجکت، CDN و مرورگر.
  8. غیرفعال‌سازی افزونه‌های جانبی: با روش نصف‌سازی، مقصر را پیدا کنید.
  9. تغییر موقت قالب: اگر خطا رفع شد، ریشه در قالب است.
  10. تماس با پشتیبانی بانک: اگر تا اینجا خطا باقی ماند، با شواهد دقیق (لاگ، زمان، شماره سفارش) با بانک تماس بگیرید.

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

اشتباهات پرهزینه در تشخیص

در پرونده‌های پشتیبانی که بازبینی کرده‌ام، این پنج اشتباه بیشتر از بقیه تکرار می‌شود:

  • متهم کردن بانک بدون بررسی سایت: در نیمی از پرونده‌ها، بانک سالم بوده اما سایت، پاسخ callback را درست پردازش نکرده. اول سایت را بررسی کنید.
  • تغییر همزمان کلید و تنظیمات: اگر همزمان کلید API را عوض کنید و تنظیمات دیگر را تغییر دهید، نمی‌دانید کدام مؤثر بوده. یک تغییر، یک تست.
  • حذف و افزودن مجدد درگاه: بعضی ادمین‌ها برای «رفع» خطا، درگاه را حذف و دوباره نصب می‌کنند. این کار می‌تواند تراکنش‌های معلق را گم کند. حذف، آخرین ابزار است نه اولین.
  • عیب‌یابی روی سایت زنده: غیرفعال کردن درگاه در ساعت شلوغ، زیان مالی مستقیم می‌سازد. همیشه روی استجینگ.
  • اعتماد به پیام‌های عمومی بانک: «خطای نامشخص» پیامی است که بانک برمی‌گرداند وقتی نمی‌داند چه شده. ریشه واقعی در سایت شماست و باید در لاگ جست‌وجو شود.

پرسش‌های پرتکرار درباره خطای درگاه پرداخت

چرا درگاه پرداخت ووکامرس اصلاً باز نمی‌شود؟ ریشه معمولاً در لایه انتقال است: فایروال سرور، مشکل cURL، یا DNS. ابتدا از داخل سرور با دستور curl به API بانک درخواست بزنید. اگر پاسخ نداد، ریشه در سرور است.

چرا پول کم می‌شود اما سفارش ثبت نمی‌شود؟ این سناریو به شکست مرحله verify در callback اشاره دارد. URL بازگشت و پاسخ verify را در لاگ درگاه بررسی کنید. اگر پاسخ خطا داشت، با شواهد با بانک تماس بگیرید و دستی سفارش بسازید.

چرا درگاه برای بعضی کاربران کار می‌کند و برای بعضی نه؟ ریشه معمولاً در لایه کش و نشست است. با تست در پنجره ناشناس، تفاوت را ببینید. صفحات /cart و /checkout باید همیشه از کش استثنا باشند.

آیا افزونه‌های امنیتی می‌توانند درگاه پرداخت را بشکنند؟ بله. بعضی فایروال‌ها، callback بانک را به‌عنوان «حمله» علامت می‌زنند و بلاک می‌کنند. IP بانک را در لیست سفید قرار دهید.

چرا بعد از افزودن SSL جدید، درگاه خطا می‌دهد؟ احتمالاً بخشی از منابع سایت هنوز روی HTTP لود می‌شوند یا گواهی جدید معتبر نیست. با ابزار آنلاین اعتبار SSL را چک کنید و ریدایرکت HTTPS را درست تنظیم کنید.

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

آیا درگاه‌های ایرانی محدودیت خاصی دارند که درگاه‌های بین‌المللی ندارند؟ بله. بعضی درگاه‌های ایرانی فقط از یک IP مشخص درخواست را می‌پذیرند و بعضی برای مبالغ بالا نیاز به تنظیمات اختصاصی دارند. همیشه شرایط را در پنل بانک بررسی کنید.

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

چرا در حالت تست درگاه کار می‌کند اما در حالت تولید نه؟ احتمالاً کلید API تولید اشتباه است یا مرچنت تولید فعال نشده. با پنل بانک تطبیق دهید.

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

مسیر پیشگیری و معماری پرداخت قابل‌اعتماد

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

  1. پایش روزانه نرخ موفقیت تراکنش: یک گزارش خودکار بسازید که نسبت تراکنش‌های موفق به ناموفق را در ۲۴ ساعت گذشته نشان دهد. اگر نرخ افت کرد، سریع ریشه را پیدا کنید — پیش از آن که به بحران تبدیل شود.
  2. محیط استجینگ با داده واقعی: فرآیند پرداخت را روی استجینگ با درگاه تست انجام دهید. محیط استجینگ با داده واقعی، تفاوت‌های پنهان را آشکار می‌کند. راه‌اندازی در بکاپ گرفتن از فروشگاه ووکامرس آمده است.
  3. مستندسازی دقیق پیکربندی درگاه: برای هر درگاه، یک برگه کوچک بسازید که کلید API، URL بازگشت، تنظیمات امنیتی و شرط‌های فعال‌سازی را ثبت کند. این سند، در روز بحران ارزش ساعات زیادی دارد.

اگر در پروژه‌ای با مشکل مشابه دست‌وپنجه نرم کرده‌اید، برای من جالب است بدانم کدام لایه بیشترین وقت شما را گرفت: کلید API، بازگشت از بانک، فایروال یا لایه کش. تجربه‌تان را در دیدگاه‌ها بنویسید؛ مخصوصاً اگر نشانه‌ای کشف کرده‌اید که در این فهرست نبوده. همین نشانه‌ها، دقیق‌ترین راهنمای نفر بعدی‌اند. 💳