اتصال زرین‌پال به ووکامرس در ۱۴۰۵: حالت آزمایشی از IP ثبت‌نشده هم جواب داد

در فروشگاه آزمایشی ووکامرسی که ساختیم، سفارشی ۱۵۰ هزار تومانی را با افزونه زرین‌پال ۵٫۱٫۱ در حالت آزمایشی پرداختیم، با مرچنت کدی ساختگی و از دستگاهی که IP آن را هیچ‌جا ثبت نکرده بودیم. درخواست با مبلغ ۱٬۵۰۰٬۰۰۰ ریال به زرین‌پال رفت، صفحه پرداخت «معادل صد و پنجاه هزار تومان» نوشت و سفارش «در حال انجام» شد.

زرین‌پال می‌نویسد از میانه شهریور ۱۴۰۵ درخواست ایجاد تراکنش فقط از IPهایی پذیرفته می‌شود که پذیرنده در پنل ثبت کرده است و این قاعده را به شاپرک نسبت می‌دهد. در آزمایش ما حالت آزمایشی آن را نسنجید، پس فروشگاهی که همه آزمایش‌ها را گذرانده باشد هم در اولین فروش واقعی می‌تواند خطا بگیرد.

آزمایش‌ها روز ۱۱ مهر ۱۴۰۵ در داکر، روی وردپرس ۷٫۱٫۲ فارسی، ووکامرس ۱۱٫۱٫۲، ووکامرس فارسی ۱۰٫۰٫۵ و PHP ۸٫۳ و با اینترنتی در ترکیه انجام شد.

اگر درگاه را قبلاً گرفته‌اید و فقط پرداخت‌ها خطا می‌دهد، از بخشی شروع کنید که با «زرین‌پال از میانه شهریور ۱۴۰۵» آغاز می‌شود و بعد نشانه‌های خطا را بخوانید. بقیه نوشته برای فروشگاهی است که تازه می‌خواهد زرین‌پال را به ووکامرس وصل کند.

اینماد، کد رهگیری مالیاتی و شبا باید به نام یک متقاضی باشد و دامنه عوض نشود

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

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

سه درگاه افزونه رایگان دارند، با کارمزد و راه آزمایش متفاوت

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

مورد	زرین‌پال	پی‌پینگ	زیبال
کارمزد هر تراکنش	۰٫۵٪ تا سقف ۱۶ هزار تومان، به‌علاوه ۵۰۰ تومان	طرح رایگان: ۱٪ تا سقف ۵ هزار تومان، به‌علاوه ۵۰۰ تومان و مالیات بر ارزش افزوده	۱٪ تا سقف ۲۰ هزار تومان، به‌علاوه ۱۰٪ مالیات بر ارزش افزوده روی کارمزد
افزونه در مخزن وردپرس	نسخه ۵٫۱٫۱، بیش از ۶۰ هزار نصب فعال	نسخه ۴٫۶٫۵، بیش از ۱ هزار نصب فعال	نسخه ۲٫۱، بیش از ۷ هزار نصب فعال
حالت آزمایشی	گزینه آزمایشی در افزونه، با هر UUID دلخواه به‌جای مرچنت کد	در افزونه نیافتیم	گزینه آزمایشی در افزونه، با مرچنت zibal

صفحه زرین‌پال درباره مالیات بر ارزش افزوده چیزی نمی‌گوید. کدام کم‌هزینه‌تر درمی‌آید به مبلغ سبد بستگی دارد. روی سفارش ۲۰۰ هزار تومانی کارمزد این نرخ‌ها ۱٬۵۰۰ تومان در زرین‌پال، ۲٬۲۰۰ در زیبال و ۲٬۵۰۰ به‌علاوه مالیات در پی‌پینگ است. روی سفارش ۲ میلیون تومانی پی‌پینگ به سقف ۵ هزار تومان می‌رسد (به‌علاوه ۵۰۰ تومان و مالیات)، زرین‌پال ۱۰٬۵۰۰ می‌گیرد و زیبال ۲۲٬۰۰۰.

این‌ها را مقایسه نهایی ندانید. شاپرک هم کارمزد می‌گیرد و جدول آن را تغییر داده است (پی‌پینگ و زرین‌پال تغییر تازه‌ای را از ۲۰ شهریور ۱۴۰۵ اعلام کرده‌اند). عدد نهایی را از پشتیبانی درگاه بپرسید.

در اتصال زرین‌پال به ووکامرس دو چیز را باید درست بگذارید: مرچنت کد و واحد پول

افزونه زرین‌پال برای ووکامرس را از «افزونه‌ها > افزودن افزونه» نصب و فعال کنید و در «ووکامرس > پیکربندی > پرداخت‌ها» زرین‌پال را باز کنید. مرچنت کد را از پنل زرین‌پال بردارید و در شروع کار «حالت آزمایشی (Sandbox)» را تیک بزنید. بالای همین صفحه افزونه یادآوری می‌کند که پرداخت واقعی نمی‌گیرد. تا این تیک روشن است، سفارش بدون پول واقعی هم «در حال انجام» می‌شود (در آزمایش ما چنین شد)، پس بعد از راه‌اندازی خاموشش کنید.

اگر قیمت‌ها را به تومان می‌نویسید، در «ووکامرس > پیکربندی > همگانی» واحد پولی را «تومان» بگذارید. افزونه مبلغ را ده برابر می‌کند: سفارش ۱۵۰ هزار تومانی ما با ۱٬۵۰۰٬۰۰۰ به زرین‌پال رفت. طبق کد افزونه، مبلغ برای «تومان»، «هزار تومان» و «هزار ریال» به ریال تبدیل می‌شود و برای «ریال» دست نمی‌خورد. اگر واحد فروشگاه را ریال بگذارید و قیمت‌ها را تومان بنویسید، مبلغ ده برابر کمتر به درگاه می‌رسد.

زرین‌پال از میانه شهریور ۱۴۰۵ درخواست را فقط از IP ثبت‌شده می‌پذیرد

زرین‌پال دو بار این را نوشته است. اطلاعیه تلگرامی‌اش (۹ شهریور) ۱۴ شهریور را تاریخ شروع می‌داند و مقاله‌ای که ثبت IP را توضیح می‌دهد ۱۵ شهریور را، با عبارت «طبق اعلام شاپرک». ما نوشته شاپرک را ندیدیم و تاریخ و این نسبت را از خود زرین‌پال نقل می‌کنیم. هر دو می‌گویند ایجاد تراکنش فقط از IPهای ثبت‌شده ممکن است.

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

برای پیدا کردن آن سه راه دارید: بخش «IP اصلی سرور» در پنل هاست، پرسیدن «IPv4 ثابت خروجی» از پشتیبانی هاست، یا اگر دسترسی SSH دارید، همین دستور:

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

طبق راهنمای زرین‌پال، در پنل آن از «تنظیمات درگاه» به زبانه «تنظیمات فنی» بروید و در بخش آی‌پی‌های سرور گزینه «با محدودیت IP» را بزنید (اطلاعیه تلگرامی نام این بخش را «ثبت و مدیریت آی‌پی‌های مجاز درگاه» نوشته). حداکثر ۵ نشانی را می‌شود با ویرگول جدا کرد. اگر هاست نشانی خروجی را گاهی عوض می‌کند، از پشتیبانی نشانی ثابت بخواهید: با هر تغییر باید دوباره ثبت کنید و تا آن موقع تراکنش‌ها خطا می‌گیرد.

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

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

حالت آزمایشی از IP ثبت‌نشده هم جواب داد

برای سندباکس زرین‌پال باید نشانی سرویس را از payment.zarinpal.com به sandbox.zarinpal.com عوض کرد و به‌جای مرچنت کد هر UUID دلخواه کافی است. افزونه با همان تیک آزمایشی نشانی را عوض می‌کند. سفارش را از تسویه حساب ثبت کردیم، در صفحه آزمایشی «پرداخت» را زدیم و بعد از تأیید افزونه، سفارش «در حال انجام» شد. افزونه زیبال در حالت آزمایشی مرچنت zibal را می‌فرستد و درخواست مستقیم ما با همین مرچنت جواب موفق گرفت. این درخواست از ترکیه رفت. در نوشته پیش‌پرداخت ووکامرس هم از همین مرچنت استفاده کردیم.

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

درگاهی که برای تسویه حساب بلوکی ساخته نشده، در آن نمی‌آید

صفحه تسویه حسابی که ووکامرس ۱۱٫۱٫۲ می‌سازد بلوکی است، یعنی با بلوک‌های ویرایشگر وردپرس ساخته می‌شود. زرین‌پال ۵٫۱٫۱ در آن نمایش داده شد، ولی افزونه درگاه ملت (نسخه ۴٫۲٫۰، آخرین به‌روزرسانی آذر ۱۴۰۰) با اینکه در تنظیمات فعال بود نیامد. ویرایشگر برگه، وقتی بلوک «تسویه حساب» را انتخاب کنید، در نوار کناری می‌نویسد «بانک ملت هنوز از این بلوک پشتیبانی نمی‌کند»:

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

اگر پرداخت جواب نداد، هر نشانه چه چیزی را نشان می‌دهد؟

صفحه سفارش بدون پیام و دکمه پرداخت

اگر خریدار «ثبت سفارش» را بزند و به صفحه‌ای برسد که شماره سفارش و مبلغ دارد ولی پیام و دکمه پرداخت ندارد، احتمالاً افزونه از زرین‌پال نشانی پرداخت نگرفته است. ما این را با مرچنت کد ساختگی و بدون حالت آزمایشی دیدیم: زرین‌پال با کد خطای منفی ۱۰ جواب داد. پیام قرمز «خطا در اتصال به درگاه پرداخت: Invalid merchant_id.» فقط بعد از بارگذاری دوباره همان صفحه آمد، هم در قالب Twenty Twenty-Five و هم در Storefront. سفارش «در انتظار پرداخت» ماند و یادداشتی نگرفت.

مستندات زرین‌پال این خطا را هم برای مرچنت کد نادرست می‌نویسد و هم برای IP نادرست: «Terminal is not valid, please check merchant_id or ip address». IP نادرست را آزمایش نکردیم، پس این پیام به‌تنهایی نمی‌گوید کدام اشتباه است. مرچنت کد، خاموش بودن حالت آزمایشی و IP ثبت‌شده را با هم ببینید.

پول رفته ولی سفارش در انتظار پرداخت مانده

اگر مشتری پرداخت کرده ولی سفارش «در انتظار پرداخت» مانده، احتمالاً درخواست بازگشت به فروشگاه نرسیده است: افزونه سفارش را وقتی کامل می‌کند که مرورگر خریدار به نشانی بازگشت فروشگاه (نشانی‌ای که با wc-api شروع می‌شود) برگردد و پرداخت تأیید شود. برای شبیه‌سازی فایروال یا افزونه امنیتی، روی آن نشانی یک قاعده مسدودکننده گذاشتیم: در صفحه سندباکس «پرداخت» را زدیم و بازگشت به فروشگاه «403 Forbidden» گرفت؛ درخواست تأییدی نرفت و سفارش «در انتظار پرداخت» ماند.

در صفحه همان سفارش دکمه «اعتبارسنجی مجدد تراکنش» هست. زدنش در آزمایش ما سفارش را به «در حال انجام» رساند و کد رهگیری گرفت؛ اگر زرین‌پال پرداخت را موفق نداند، افزونه سفارش را کامل نمی‌کند. علت را در فایروال، کلودفلر یا افزونه امنیتی بگردید: قاعده‌ای که نشانی‌های wc-api را می‌بندد.

وقتی مشکل از دامنه، درخواست‌های خروجی یا هاست است

اگر دامنه فروشگاه را عوض کرده‌اید یا پرداخت را به زیردامنه برده‌اید، پیش از فروش دامنه تازه را به زرین‌پال اطلاع دهید؛ زرین‌پال و زیبال ناهماهنگی دامنه را خطا می‌شمارند. و اگر سایت را برای نت ملی با WP_HTTP_BLOCK_EXTERNAL بسته‌اید، نشانی درگاه باید در WP_ACCESSIBLE_HOSTS باشد (زرین‌پال ۵٫۱٫۱ از جمله به payment.zarinpal.com و در حالت آزمایشی به sandbox.zarinpal.com درخواست می‌فرستد). هر سه افزونه، یعنی زرین‌پال ۵٫۱٫۱، پی‌پینگ ۴٫۶٫۵ و زیبال ۲٫۱، از API وردپرس استفاده می‌کنند؛ توضیحش در نوشته کندی وردپرس در نت ملی آمده است.

اگر IP خروجی، فایروال یا تنظیمات هاست دست شما نیست، درخواست پشتیبانی را با گزینه ووکامرس ثبت کنید و بنویسید پرداخت چه خطایی می‌دهد. توضیح خدمات در صفحه پشتیبانی فنی وردپرس هست.

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