آموزش جامع و کاربردی تنظیم درگاه زرین‌پال در ووکامرس + حل تمامی خطاها

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

۱. پیش‌نیازهای فنی و قانونی اتصال زرین‌پال به ووکامرس

برای راه اندازی درگاه پرداخت زرین‌پال روی ووکامرس به یک حساب احراز هویت شده در زرین‌پال، مرچنت کد (Merchant ID)، گواهی SSL فعال روی دامنه و ماژول cURL فعال در سرور هاست نیاز دارید.

قبل از شروع پیکربندی در وردپرس، مطمئن شوید موارد زیر را آماده کرده‌اید:

• حساب کاربری تایید شده: مدارک هویتی شما در زرین‌پال باید کاملاً تایید شده باشد.
• کد درگاه (Merchant ID): یک رشته ۳۶ کاراکتری اختصاصی که پس از ایجاد درگاه در پنل زرین‌پال دریافت می‌کنید.
• کد مالیاتی (اینماد و پرونده مالیاتی): طبق قوانین جدید، برای فعال‌سازی درگاه پرداخت باید پرونده مالیاتی فعال داشته باشید و کد رهگیری ثبت‌نام مالیاتی در پنل زرین‌پال ثبت شده باشد.
• نماد SSL فعال: آدرس سایت شما باید حتماً با https شروع شود، در غیر این صورت ارتباط امن برقرار نشده و بازگشت از درگاه با خطا مواجه می‌شود.

۲. مقایسه درگاه واسط و درگاه اختصاصی (زرین‌لین / مستقیم)

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

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

برای راه اندازی فنی، مراحل زیر را با دقت دنبال کنید:

1. نصب افزونه: به پیشخوان وردپرس رفته، از بخش افزونه‌ها > افزودن، عبارت “Zarinpal WooCommerce” را جستجو کنید. افزونه رسمی منتشر شده توسط زرین‌پال را نصب و فعال کنید.
2. ورود به تنظیمات درگاه: در پیشخوان وردپرس به مسیر ووکامرس > پیکربندی > تب پرداخت‌ها بروید.
3. فعال‌سازی درگاه: گزینه «زرین‌پال» را پیدا کرده و کلید مقابل آن را روی حالت روشن قرار دهید، سپس روی دکمه مدیریت / تنظیمات کلیک کنید.
4. وارد کردن مرچنت کد: کد ۳۶ رقمی دریافت شده از پنل زرین‌پال را در فیلد مرچنت کد (Merchant ID) کپی کنید. دقت کنید هیچ فاصله اضافی (Space) قبل یا بعد از کد وجود نداشته باشد.
5. تنظیم پیام‌های پرداخت: متن پیام‌های پرداخت موفق و ناموفق را شخصی‌سازی کنید. می‌توانید از شورت‌کدهای راهنما مانند {transaction_id} برای نمایش کد پیگیری به کاربر استفاده کنید.

۴. تنظیم صحیح واحد پول (جلوگیری از خطای ۱۰ برابری قیمت)

شایع‌ترین اشتباه در تنظیم درگاه زرین‌پال، عدم هماهنگی واحد پول ووکامرس با واحد پول انتخابی در تنظیمات افزونه است که باعث می‌شود محصولات ۱۰ برابر گران‌تر یا ۱۰ برابر ارزان‌تر به بانک ارسال شوند.

زرین‌پال مبالغ را برپایه ریال به وب‌سرویس بانک ارسال می‌کند. برای حل این موضوع:

• اگر واحد پول فروشگاه شما در مسیر ووکامرس > پیکربندی > همگانی روی تومان تنظیم شده است، در تنظیمات افزونه زرین‌پال نیز واحد پول را روی تومان بگذارید تا افزونه به‌صورت خودکار قیمت را ضرب‌در ۱۰ کرده و به ریال تبدیل کند.
• اگر واحد پول اصلی سایت روی ریال است، در افزونه نیز گزینه ریال را انتخاب کنید تا محاسبات بدون تغییر به بانک فرستاده شود.

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

۵. نحوه تست پرداخت در محیط سندباکس (Sandbox)

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

۶. ۳ نکته حیاتی برای جلوگیری از قطعی و اختلال در پرداخت آنلاین

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

الف) استثنا کردن آدرس Callback از افزونه‌های کش

افزونه‌های کش مانند LiteSpeed Cache یا WP Rocket ممکن است آدرس بازگشت زرین‌پال را کش کنند. این کار باعث می‌شود پاسخ بانک به وردپرس نرسد. حتماً آدرس‌های زیر را در بخش Exclude افزونه کش خود وارد کنید:

/wc-api/WC_Zarinpal/
/?wc-api=WC_Zarinpal

ب) بررسی تداخل با فایروال کلودفلر (Cloudflare)

اگر از کلودفلر یا سیستم‌های ابری استفاده می‌کنید، ممکن است آی‌پی‌های سرور زرین‌پال توسط فایروال بلاک شوند. برای جلوگیری از این مشکل، IPهای رسمی زرین‌پال را در بخش Firewall Rules کلودفلر در لیست مجاز (Allow) قرار دهید.

ج) بهینه‌سازی استایل صفحه تسویه‌حساب

گاه به دلیل تداخل استایل قالب، دکمه پرداخت زرین‌پال در موبایل نامرئی یا غیرقابل کلیلک می‌شود. با افزودن کدهای استاندارد در بخش استایل‌های کاربردی CSS می‌توانید ظاهر دکمه‌های پرداخت را در تمامی رزولوشن‌ها کاملاً ریسپانسیو و مشخص کنید.

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

کد خطاهای زرین‌پال اعداد منفی هستند که علت عدم اتصال یا شکست تراکنش را مشخص می‌کنند.

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

۸. پرسش‌های متداول