راهنمای جامع اتصال درگاه پرداخت مستقیم و واسط به ووکامرس (گام‌به‌گام و کاربردی)

راهنمای گام‌به‌گام پیکربندی درگاه پرداخت در ووکامرس

گام اول: انتخاب و نصب افزونه رسمی

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

# ساختار استاندارد مسیر درگاه‌های ووکامرس در هاست
/wp-content/plugins/woocommerce-gateway-zarinpal/
/wp-content/plugins/behpardakht-woocommerce/

گام دوم: تنظیمات واحد پول و صفحه تسویه‌حساب

پیش از تنظیم کلیدهای API، واحد پولی ووکامرس را تعیین کنید:

• به مسیر ووکامرس > پیکربندی > تب عمومی (General) بروید.
• در بخش پیکربندی واحد پول، واحد ارزی را مشخص کنید (تومان یا ریال).
• به مسیر ووکامرس > پیکربندی > تب پرداخت‌ها (Payments) مراجعه نمایید. در این صفحه لیست تمام درگاه‌های نصب‌شده نمایش داده می‌شود.

گام سوم: مقداردهی کلیدهای ارتباطی (API Credentials)

روی درگاه مورد نظر (مثلاً زرین‌پال یا به‌پرداخت) کلیک کرده و موارد زیر را تنظیم کنید:

آموزش کامل HTML از صفر تا صد | دوره جامع HTML5 با زیرنویس فارسی

550,000 تومان

مشاهده و خرید

• فعال‌سازی درگاه (Enable/Disable): تیک فعال‌سازی را بزنید.
• عنوان درگاه (Title): متنی بنویسید که در مرحله تسویه‌حساب به مشتری نمایش داده می‌شود (مثال: پرداخت امن اینترنتی با تمامی کارت‌های عضو شتاب).
• مرچنت کد (Merchant ID) یا کلید API: این شناسه یکتا را مستقیماً از پنل پذیرندگی کپی کرده و بدون هیچ‌گونه فاصله (Space) در ابتدا یا انتها وارد کنید.
• تنظیمات درگاه مستقیم بانک ملت (به‌پرداخت): فیلدهای Terminal ID (شماره ترمینال)، Username (نام کاربری) و Password (کلمه عبور) دریافتی از بهشت شاپرک یا بانک را درج کنید.

// نمونه شماتیک اعتبارسنجی بازگشت درگاه در اکشن هوک ووکامرس
add_action('woocommerce_api_callback_gateway_handler', function() {
    $authority = sanitize_text_field($_GET['Authority'] ?? '');
    $status    = sanitize_text_field($_GET['Status'] ?? '');

    if ($status === 'OK' && !empty($authority)) {
        // فراخوانی متد اعتبارسنجی سرور به سرور (Verification Request)
        $response = verify_payment_with_gateway($authority);
        if ($response['success']) {
            $order = wc_get_order($response['order_id']);
            $order->payment_complete($response['ref_id']);
            $order->add_order_note('پرداخت با موفقیت انجام شد. کد پیگیری: ' . $response['ref_id']);
            wp_safe_redirect($order->get_checkout_order_received_url());
            exit;
        }
    }
    wc_add_notice('پرداخت ناموفق بود یا توسط کاربر لغو شد.', 'error');
    wp_safe_redirect(wc_get_checkout_url());
    exit;
});

استراتژی پیاده‌سازی هم‌زمان درگاه پشتیبان (Fallback Gateway)

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

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

خطایابی و رفع چالش‌های متداول بازگشت از بانک

+------------------------------------+-------------------------------------------+----------------------------------------------+
| خطای فنی / مشکل                     | علت اصلی                                  | روش رفع مشکل                                 |
+------------------------------------+-------------------------------------------+----------------------------------------------+
| خطای عدم تطابق دامنه (Invalid IP)  | تغییر IP هاست یا عدم ثبت دامنه در پنل بانک| ثبت IP سرور و دامنه‌های متصل در پرتال پذیرنده|
| صفحه سفید هنگام بازگشت از درگاه    | تداخل کش یا خطای PHP Fatal                | غیرفعال‌سازی کش صفحه تسویه و بررسی error_log |
| سفارش ناموفق با وجود کسر وجه       | عدم اجرای متد Verify در زمان مناسب        | بررسی زمان Timeout سرور و هماهنگی وب‌هوک     |
| خطای نشانی بازگشت (Callback Mismatch)| تفاوت آدرس با WWW و بدون WWW               | یکسان‌سازی URL در تنظیمات وردپرس و پنل بانک |
| تغییر نکردن وضعیت سفارش            | بلاک شدن ریکوئست بازگشت توسط فایروال هاست | مستثنی کردن آی‌پی‌های شاپرک در ModSecurity   |
+------------------------------------+-------------------------------------------+----------------------------------------------+

۱. تنظیم صحیح نشانی بازگشت (Callback URL)

اگر کاربر پس از ورود اطلاعات کارت بانکی با خطای Invalid Callback URL یا ارور ۴۰۴ روبه‌رو می‌شود، ساختار پیوند‌های یکتا (Permalinks) در وردپرس را بررسی کنید:

• به مسیر تنظیمات > پیوندهای یکتا رفته و ساختار را روی نام نوشته بگذارید و ذخیره کنید تا فایل .htaccess نوسازی شود.
• مطمئن شوید دامنه ثبت‌شده در پنل درگاه دقیقاً با پروتکل (https://) و پیشوند سایت (www یا بدون www) در تنظیمات همخوانی دارد.

۲. استثنا کردن صفحات تسویه از سیستم‌های کشینگ

افزونه‌های بهینه‌سازی سرعت و کش مانند WP Rocket، LiteSpeed Cache یا تنظیمات کش لایه CDN (مانند Cloudflare یا ابرآروان) نباید صفحات حساس ووکامرس را کش کنند. آدرس‌های زیر را در لیست استثنای کش (Never Cache URLs) قرار دهید:

/checkout/
/cart/
/my-account/
/?wc-api=*

۳. بررسی خطای تفاوت ارزی (ریال به تومان)

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

چک‌لیست آزمایش نهایی پیش از آغاز فروش رسمی

قبل از اعلام عمومی فروشگاه، مراحل زیر را با کارت بانکی واقعی اجرا کنید:

• [ ] ایجاد یک محصول تستی با حداقل مبلغ ممکن (مثلاً ۱۰,۰۰۰ تومان).
• [ ] تست پرداخت موفق و اطمینان از تغییر وضعیت سفارش به «در حال انجام» در پیشخوان وردپرس.
• [ ] ذخیره‌سازی صحیح کد رهگیری (RefID) در بخش یادداشت‌های سفارش.
• [ ] تست سناریوی انصراف از پرداخت و بررسی هدایت کاربر به صفحه سبد خرید همراه با پیام خطای مشخص.
• [ ] تست سناریوی ورود اطلاعات اشتباه کارت و بررسی پیام خطای بازگشتی.
• [ ] آزمایش فرایند خرید با تلفن همراه و مرورگرهای مختلف (Chrome, Safari, Firefox).
• [ ] اطمینان از ارسال خودکار ایمیل و پیامک فاکتور به مشتری و مدیر فروشگاه.

جمع‌بندی و نتیجه‌گیری

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