«درگاه کار نمی‌کند» می‌تواند چند رخداد کاملاً متفاوت باشد: روش پرداخت اصلاً در Checkout دیده نمی‌شود، دکمه ثبت سفارش خطا می‌دهد، درخواست ساخت تراکنش رد می‌شود، انتقال به صفحه بانک انجام نمی‌شود یا کاربر پس از پرداخت به سایت برمی‌گردد اما سفارش تأیید نمی‌شود. تا مرحله شکست مشخص نشود، تعویض افزونه درگاه بیشتر شواهد را از بین می‌برد.
پاسخ سریع: پیش از تلاش دوباره، بخش سفارش‌ها و تراکنش‌های پنل درگاه را بررسی کنید تا پرداخت قبلی تکرار نشود. سپس با یک سفارش کنترل‌شده، timestamp، شماره سفارش، status و شناسه غیرحساس تراکنش را ثبت کنید. Network مرورگر، لاگ ووکامرس/PHP و گزارش پنل درگاه را در همان بازه کنار هم بگذارید.
خرابی دقیقاً در کدام مرحله است؟
| نشانه | لایه محتمل | شاهد لازم |
|---|---|---|
| روش پرداخت نمایش داده نمی‌شود | فعال‌سازی، ارز، کشور، روش ارسال یا شرط افزونه | تنظیمات و پیام Checkout |
| ثبت سفارش قبل از انتقال متوقف می‌شود | validation، JavaScript، PHP یا ساخت سفارش | Ajax response و log |
| API درگاه خطا می‌دهد | credential، مبلغ، callback، شبکه یا TLS | کد خطای رسمی و request ID |
| بانک باز می‌شود ولی بازگشت خراب است | callback، route، WAF یا DNS | redirect chain و access log |
| پرداخت موفق، سفارش ناموفق | verify/webhook یا mapping وضعیت | شناسه تراکنش و log verification |
وقتی روش پرداخت دیده نمی‌شود
فعال بودن افزونه کافی نیست. بسیاری از درگاه‌ها بر اساس ارز، کشور صورتحساب، مبلغ حداقل/حداکثر، نوع محصول، subscription یا روش ارسال availability را تعیین می‌کنند. پیام‌های Console و Checkout را بررسی و تنظیمات را با مستندات همان نسخه افزونه تطبیق دهید. ارز نمایشی و واحدی که API انتظار دارد—برای نمونه ریال یا تومان—را حدس نزنید.
Checkout و JavaScript
اگر کلیک روی ثبت سفارش request نمی‌سازد، نخستین خطای Console، اعتبارسنجی فیلد و تداخل قالب را ببینید. اگر request ساخته می‌شود، status و response آن مهم است؛ پاسخ 200 نیز ممکن است payload خطا داشته باشد. چندبار کلیک‌کردن یا refresh هنگام Pending ممکن است سفارش یا تلاش پرداخت دیگری بسازد.
اعتبارنامه‌ها و محیط آزمایشی
شناسه پذیرنده، کلید API یا secret باید مربوط به همان محیط production/sandbox و همان دامنه باشد. secret را در screenshot، ticket عمومی، repository یا log قرار ندهید. وجود فاصله، newline، credential لغوشده یا محدودیت IP را از پنل رسمی بررسی کنید. بعد از افشای احتمالی، کلید را از مسیر رسمی rotate کنید؛ پنهان کردن متن در رابط، افشا را خنثی نمی‌کند.
مبلغ، واحد پول و گرد کردن
مبلغ سفارش در ووکامرس، مبلغ ارسال‌شده به API و مبلغ ثبت‌شده در پنل درگاه را مقایسه کنید. تبدیل اشتباه ریال/تومان، اعشار، تخفیف، هزینه ارسال یا مالیات می‌تواند verification را رد کند. اصلاح را با چند مبلغ کنترل‌شده—including کوپن و ارسال—تست کنید و منطق مبلغ را در چند افزونه تکرار نکنید.
ارتباط سرور با API درگاه
ساخت تراکنش معمولاً از سرور فروشگاه انجام می‌شود. DNS، اتصال TCP، TLS، timeout، proxy خروجی و پاسخ HTTP را بررسی کنید. خاموش کردن بررسی گواهی TLS راه‌حل نیست و امکان حمله میانی را بالا می‌برد. اگر IP خروجی باید whitelist شود، IP واقعی NAT را از مسیر معتبر مشخص کنید.
خطای timeout به معنی ناموفق بودن قطعی تراکنش نیست؛ ممکن است درگاه درخواست را پذیرفته ولی پاسخ به فروشگاه نرسیده باشد. قبل از retry، با شناسه یکتا یا API inquiry وضعیت را جویا شوید. retry باید idempotent باشد تا یک سفارش چند پرداخت نسازد.
Callback و Webhook
درگاه باید بتواند URL بازگشت یا webhook را از اینترنت و با HTTPS معتبر فراخوانی کند. redirect زبان، اجبار ورود، maintenance mode، Basic Auth، WAF، Geo-block و cache می‌توانند callback را متوقف کنند. URL دقیق ارسال‌شده به درگاه را با URL ثبت‌شده در پنل مقایسه کنید؛ دامنه با/بدون www و scheme متفاوت محسوب می‌شوند.
زمان سیستم، گواهی و امضای درخواست
درگاه‌هایی که request امضاشده یا timestamp محدود دارند، به ساعت درست سرور وابسته‌اند. وضعیت همگام‌سازی زمان و تاریخ انقضای زنجیره گواهی را بررسی کنید؛ timezone نمایشی فروشگاه با clock سیستم یکی نیست. ساعت را برای عبور از validation دستی عقب‌وجلو نکنید. ریشه اختلاف NTP، container یا host را اصلاح و سپس یک درخواست تازه بسازید.
اگر خطا به signature مربوط است، رشته canonical، encoding، ترتیب فیلدها و credential همان محیط را طبق مستندات رسمی افزونه/درگاه بررسی کنید. الگوریتم امضا را برای «قبول شدن» ضعیف یا مقایسه امن را حذف نکنید.
از کدام لاگ‌ها استفاده کنیم؟
- WooCommerce Status → Logs برای source مربوط به درگاه
- PHP error log برای fatal/exception در همان timestamp
- access/error log وب‌سرور برای callback و status upstream
- Network مرورگر برای درخواست ثبت سفارش و redirect
- پنل درگاه برای وضعیت و کد خطای رسمی تراکنش
لاگ تشخیصی افزونه را فقط به‌اندازه لازم فعال کنید و بعد از آزمون خاموش یا محدود کنید. شماره کارت، CVV، رمز، secret، token کامل، cookie و داده شخصی نباید ثبت یا منتشر شوند.
WAF، Cache و افزونه امنیتی
برای false positive، rule ID و request مشخص را پیدا و استثنای حداقلی ایجاد کنید. خاموش‌کردن کامل WAF، CSRF protection یا rate limit قابل قبول نیست. صفحات Cart، Checkout و callback نباید پاسخ عمومی cacheشده داشته باشند؛ ولی bypass بیش‌ازحد نیز کل فروشگاه را بی‌دلیل از cache خارج می‌کند.
ناسازگاری نسخه و Hookها
پس از به‌روزرسانی WooCommerce، PHP، قالب یا افزونه درگاه ممکن است signature، Checkout Block یا HPOS با نسخه افزونه ناسازگار شود. changelog و requirement رسمی را بررسی کنید. rollback فایل بدون بررسی migration دیتابیس خطر دارد؛ clone هم‌نسخه بسازید و سفارش‌های جدید production را هنگام برنامه بازگشت در نظر بگیرید.
مدیریت رخداد هنگام قطع یا ناپایداری درگاه
اگر نرخ خطا ناگهان برای همه کاربران بالا رفته، یک incident با زمان شروع، نسخه آخرین deployment و نمونه request ID ثبت کنید. وضعیت رسمی ارائه‌دهنده و خطاهای شبکه خروجی را جدا بررسی کنید. درگاه جایگزین را فقط وقتی نمایش دهید که پیکربندی، تسویه، callback و تجربه refund آن قبلاً آزموده شده باشد؛ افزودن عجولانه یک افزونه پرداخت ناشناخته در میانه قطعی ریسک بیشتری ایجاد می‌کند.
پیام Checkout باید شفاف باشد و مشتری را به کلیک پی‌درپی تشویق نکند. اگر احتمال پذیرش درخواست وجود دارد، به کاربر بگویید پیش از تلاش مجدد وضعیت سفارش و حساب را بررسی کند. پس از رفع رخداد، سفارش‌های Pending و تراکنش‌های بازه خطا را reconcile کنید؛ بازگشت سرویس به‌تنهایی پرونده پرداخت‌های قبلی را نمی‌بندد.
روند تشخیص امن
- فروش را متوقف نکنید؛ ابتدا دامنه اثر و وضعیت تراکنش‌های جاری را مشخص کنید.
- backup، staging و یک روش/مبلغ آزمایشی مورد تأیید فراهم کنید.
- مرحله شکست و request/response غیرحساس را ثبت کنید.
- کد خطا را در مستندات رسمی همان درگاه تفسیر کنید.
- تنظیمات ارز، callback، credential و availability را بررسی کنید.
- شبکه، TLS، WAF و logهای server را با timestamp تطبیق دهید.
- پس از اصلاح، کل چرخه ایجاد، پرداخت، verify و تغییر وضعیت را تست کنید.
Smoke Test بعد از اصلاح
- مهمان و کاربر واردشده
- محصول فیزیکی و در صورت وجود مجازی
- ارسال، تخفیف و مالیات
- پرداخت موفق و لغوشده
- بازگشت مرورگر و webhook مستقل
- وضعیت سفارش، موجودی، ایمیل و refund آزمایشی
اگر پس از پرداخت، سفارش همچنان Failed یا Pending می‌ماند، راهنمای پرداخت موفق با سفارش ناموفق را دنبال کنید. اگر انتقال آغاز نمی‌شود و spinner باقی می‌ماند، مسیر تشخیص Checkout گیرکرده مناسب‌تر است.
اشتباه‌های رایج
- پرداخت مکرر برای «امتحان دوباره» بدون بررسی تراکنش قبلی
- تعویض هم‌زمان درگاه، قالب و cache
- انتشار secret در log یا پیام پشتیبانی
- خاموش کردن TLS verification یا WAF
- تفسیر timeout به‌عنوان شکست قطعی
- تغییر دستی وضعیت سفارش بدون reconcile مالی
- آزمون فقط redirect و نادیده گرفتن verify/webhook
چه زمانی کمک تخصصی لازم است؟
اگر پول از مشتری کسر می‌شود، تراکنش‌ها وضعیت متناقض دارند یا callback به‌صورت متناوب می‌رسد، آزمون بیشتر روی production ریسک مالی دارد. پشتیبانی فروشگاه ووکامرس می‌تواند لاگ فروشگاه، وب‌سرور و پنل درگاه را با شناسه تراکنش reconcile و نقطه شکست را بدون دستکاری کور سفارش پیدا کند.
پرسش‌های متداول
آیا پاک کردن Cache مشکل درگاه را حل می‌کند؟
فقط اگر پاسخ یا asset قدیمی عامل باشد؛ خطای credential، API، مبلغ یا callback با purge حل نمی‌شود.
چرا درگاه برای مدیر دیده می‌شود ولی برای مشتری نه؟
شرایط availability، کشور، ارز، روش ارسال، cache و session دو کاربر را مقایسه کنید.
آیا فعال کردن Debug امن است؟
اگر محدود، موقت و با redaction باشد. نمایش خطا به کاربر یا ثبت secret و داده پرداخت امن نیست.
در timeout باید سفارش را دوباره پرداخت کرد؟
خیر؛ ابتدا وضعیت سفارش و پنل درگاه یا inquiry را بررسی کنید تا پرداخت تکراری رخ ندهد.