پیش از راه‌اندازی درگاه، تنظیمات ووکامرس، هاست و حساب پذیرنده را بررسی کنید. این کار به پیشگیری از مشکلاتی مثل نمایش‌ندادن درگاه، مبلغ نادرست یا ثبت‌نشدن نتیجه پرداخت در سفارش کمک می‌کند.
این راهنما مبنای مشترک درگاه‌های زرین‌پال، زیبال، سامان SEP، به‌پرداخت ملت و پرداخت اقساطی اسنپ‌پی در جم پک است. اطلاعات اختصاصی مانند شناسه پذیرنده، نام کاربری، رمز، کلید یا نشانی بازگشت هر سرویس در مستند جداگانه همان درگاه توضیح داده می‌شود.
درگاه‌های موجود و سطح دسترسی
در نسخه بررسی‌شده، پنج روش پرداخت در اختیار فروشگاه قرار دارد:
| درگاه | نوع پرداخت | سطح دسترسی |
|---|---|---|
| زرین‌پال | پرداخت آنلاین | رایگان |
| زیبال | پرداخت آنلاین | رایگان |
| سامان SEP | پرداخت آنلاین بانکی | Pro |
| به‌پرداخت ملت | پرداخت آنلاین بانکی | Pro |
| اسنپ‌پی | پرداخت اقساطی | Pro |
هر درگاه به‌صورت مستقل فعال می‌شود. فعال‌بودن یک درگاه، درگاه‌های دیگر را فعال یا پیکربندی نمی‌کند. برای درگاه‌های Pro باید لایسنس معتبر و دسترسی لازم نیز برقرار باشد.
فرایند کلی یک پرداخت
جزئیات ارتباط با سرویس‌ها متفاوت است، اما جریان معمول پرداخت به این صورت انجام می‌شود:
- مشتری روش پرداخت را در تسویه‌حساب انتخاب می‌کند.
- ووکامرس سفارش را با وضعیت پرداخت‌نشده ایجاد می‌کند.
- درگاه مبلغ و اطلاعات لازم را برای سرویس پرداخت می‌فرستد.
- سرویس یک توکن، شناسه یا پاسخ اولیه برمی‌گرداند.
- مشتری به صفحه پرداخت سرویس هدایت می‌شود.
- پس از پرداخت، لغو یا خطا، مشتری به مسیر بازگشت فروشگاه (Callback) هدایت می‌شود.
- سرور سایت، نتیجه را از سرویس پرداخت استعلام می‌کند یا برای تأیید می‌فرستد.
- فقط پس از تأیید معتبر، پرداخت در ووکامرس تکمیل و شناسه تراکنش ثبت می‌شود.
- مشتری صفحه نتیجه سفارش را می‌بیند و مدیر می‌تواند جزئیات را در سفارش و یادداشت‌های آن بررسی کند.
بازگشت موفق مرورگر به سایت به‌تنهایی اثبات پرداخت نیست. نتیجه باید با پاسخ معتبر سرویس پرداخت تأیید شود و سپس ووکامرس عملیات تکمیل پرداخت را انجام دهد.
محل تنظیمات درگاه‌ها
برای مدیریت درگاه‌ها:
- وارد پیشخوان وردپرس شوید.
- از منوی جم پک، «درگاه‌های پرداخت» را انتخاب کنید.
- پنل درگاه موردنظر را باز کنید.
- تنظیمات پایه، اطلاعات حساب و گزینه‌های عملیاتی را تکمیل کنید.
- تغییرات را ذخیره کنید.
نشانی صفحه تنظیمات:
/wp-admin/admin.php?page=gempack#payment-gatewaysووکامرس نیز در مسیر «ووکامرس ← پیکربندی ← پرداخت‌ها» سوییچ فعال‌سازی روش‌ها را نشان می‌دهد. تغییر وضعیت فعال‌سازی از آن صفحه با تنظیم مربوط در جم پک همگام می‌شود؛ بااین‌حال برای جلوگیری از پراکندگی تنظیمات، صفحه «درگاه‌های پرداخت» جم پک را مرجع اصلی پیکربندی در نظر بگیرید.
اگر از صفحه اختصاصی تنظیمات یک درگاه در ووکامرس وارد شوید، مدیریت تنظیمات به بخش مربوط در جم پک هدایت می‌شود.
گروه‌های مشترک تنظیمات
فیلدهای دقیق هر سرویس یکسان نیستند، اما تنظیمات معمولاً در سه گروه قرار می‌گیرند.
تنظیمات پایه
- فعال‌سازی: درگاه را برای نمایش در تسویه‌حساب فعال می‌کند؛
- عنوان: نامی که مشتری هنگام انتخاب روش پرداخت می‌بیند؛
- توضیحات: متن کوتاهی که زیر عنوان درگاه در Checkout نمایش داده می‌شود؛
- حالت آزمایشی: فقط در درگاه‌هایی نمایش داده می‌شود که چنین حالتی را پشتیبانی می‌کنند.
عنوان باید کوتاه، روشن و متناسب با تجربه مشتری باشد. برای نمونه، «پرداخت آنلاین با زرین‌پال» از یک عنوان داخلی یا فنی قابل‌فهم‌تر است. در توضیحات، اطلاعات محرمانه یا وعده‌ای که سرویس ارائه نمی‌کند ننویسید.
اطلاعات حساب پذیرنده
این بخش شامل شناسه‌ها و اطلاعاتی است که سرویس پرداخت در اختیار پذیرنده قرار می‌دهد. حداقل اطلاعات اصلی درگاه‌ها عبارت‌اند از:
| درگاه | شناسه اصلی | اطلاعات تکمیلی احتمالی |
|---|---|---|
| زرین‌پال | Merchant ID | تنظیم حالت آزمایشی در صورت نیاز |
| زیبال | Merchant ID | تنظیم حالت آزمایشی در صورت نیاز |
| سامان SEP | Terminal ID | اطلاعات قرارداد یا پذیرندگی مطابق پنل سرویس |
| به‌پرداخت ملت | Terminal ID | نام کاربری و رمز پذیرنده |
| اسنپ‌پی | Client ID | Client Secret، نام کاربری و رمز |
مقادیر را از پنل یا قرارداد همان درگاه کپی کنید. شناسه ترمینال و پذیرنده را با هم اشتباه نگیرید و اطلاعات محیط واقعی و آزمایشی را جدا نگه دارید. فاصله اضافی یا اطلاعات درگاه دیگر هم ممکن است اتصال را ناموفق کند.
اگر یک درگاه فعال باشد ولی فیلد الزامی آن خالی بماند، جم پک هشدار مدیریتی نمایش می‌دهد و نام فیلد ناقص را مشخص می‌کند.
تنظیمات عملیاتی و پیام‌ها
بسته به درگاه، می‌توانید پیام‌های پرداخت موفق، ناموفق یا لغوشده و برخی گزینه‌های گزارش‌گیری را تنظیم کنید. متن پیام، نتیجه را به مشتری توضیح می‌دهد؛ برای تأیید پرداخت، وضعیت تراکنش و سفارش را بررسی کنید.
متن پیام باید:
- نتیجه را روشن و بدون اصطلاح فنی بیان کند؛
- مشتری را برای مشاهده سفارش یا تلاش دوباره راهنمایی کند؛
- اطلاعات داخلی، پاسخ خام درگاه یا جزئیات امنیتی را افشا نکند؛
- شماره پیگیری را فقط زمانی نمایش دهد که از پاسخ تأییدشده سرویس دریافت شده باشد.
نگهداری امن اطلاعات پذیرنده
اطلاعات اتصال درگاه مانند رمز عبور، Client Secret و برخی شناسه‌ها باید محرمانه نگه داشته شوند.
- اطلاعات واقعی را در تصویر آموزشی، ویدئو یا تیکت عمومی نمایش ندهید؛
- برای محیط آزمایشی و عملیاتی از اطلاعات جداگانه استفاده کنید؛
- دسترسی مدیرانی را که می‌توانند تنظیمات درگاه را ببینند محدود کنید؛
- رمزها را در متن برگه، کد قالب یا ابزارهای آمار وارد نکنید؛
- هنگام اشتراک لاگ، توکن، رمز، شماره کارت، موبایل و اطلاعات مشتری را حذف کنید؛
- پس از احتمال افشا، اطلاعات دسترسی را از پنل سرویس تعویض کنید؛
- از ذخیره‌کردن اطلاعات پذیرنده داخل مستند داخلی بدون کنترل دسترسی خودداری کنید.
شناسه عمومی پذیرنده ممکن است به‌اندازه رمز حساس نباشد، اما بهتر است همان سیاست محافظتی را برای تمام اطلاعات اتصال اجرا کنید.
ریال، تومان و مبلغ ارسالی
درگاه‌ها درباره واحد و مقیاس مبلغ رفتار یکسانی ندارند؛ بنابراین نباید یک ضریب تبدیل عمومی را برای همه آن‌ها فرض کرد. جم پک تبدیل لازم را در پیاده‌سازی هر درگاه انجام می‌دهد، اما تنظیم واحد پول ووکامرس و آزمون مبلغ همچنان ضروری است.
پیش از انتشار درگاه:
- واحد پول فروشگاه را در ووکامرس بررسی کنید.
- یک محصول با مبلغ مشخص و ساده ایجاد کنید.
- هزینه ارسال، مالیات، تخفیف و جمع نهایی را یادداشت کنید.
- سفارش آزمایشی را تا صفحه پرداخت ادامه دهید.
- مبلغ نمایش‌داده‌شده در سرویس پرداخت را با جمع نهایی سفارش مقایسه کنید.
- پس از بازگشت، مبلغ تأییدشده و یادداشت سفارش را بررسی کنید.
برای نمونه، اگر فروشگاه تومان نمایش می‌دهد، صرفاً از روی عدد ذخیره‌شده در ووکامرس نتیجه نگیرید که همه درگاه‌ها باید مبلغ را در ۱۰ ضرب کنند. معیار نهایی، مبلغ درست در صفحه پرداخت و تأیید همان مبلغ برای سفارش است.
آزمون را دست‌کم برای این حالت‌ها تکرار کنید:
- محصول ساده بدون تخفیف؛
- محصول دارای فروش ویژه؛
- سفارش دارای کد تخفیف؛
- سفارش دارای هزینه ارسال؛
- سفارش دارای مالیات، در صورت استفاده؛
- محصول متغیر؛
- مبلغ نزدیک حداقل یا حداکثر مجاز سرویس.
Callback چیست؟
Callback مسیری در سایت است که سرویس پرداخت پس از عملیات مشتری به آن بازمی‌گردد. این مسیر اطلاعات اولیه تراکنش را دریافت می‌کند و درگاه از طریق ارتباط سمت سرور، نتیجه را با سرویس پرداخت تطبیق می‌دهد.
جم پک Callback درگاه‌ها را با سازوکار WC-API ووکامرس ثبت می‌کند. شناسه‌های فنی نسخه بررسی‌شده عبارت‌اند از:
| درگاه | شناسه Callback |
|---|---|
| زرین‌پال | aio_wc_zarinpal_return و مسیر تأیید aio_wc_zarinpal_verify |
| زیبال | aio_wc_zibal |
| سامان SEP | aio_wc_saman |
| به‌پرداخت ملت | aio_wc_mellat |
| اسنپ‌پی | aio_wc_snappay؛ مسیر قدیمی wc_gateway_snapppay نیز پذیرفته می‌شود |
بسته به پیکربندی پیوندهای یکتا، URL فنی Callback می‌تواند ساختاری مشابه یکی از نمونه‌های زیر داشته باشد:
https://example.com/wc-api/CALLBACK_ID/
https://example.com/?wc-api=CALLBACK_IDاین نمونه‌ها را به‌عنوان URL نهایی پنل پذیرندگی کپی نکنید. نشانی دقیق هر سرویس را از مستند اختصاصی همان درگاه یا مقداری که در تنظیمات نمایش داده می‌شود بردارید؛ زیرا مسیر، پارامترها و مرحله تأیید درگاه‌ها متفاوت است.
شرایط لازم برای دسترسی Callback
- URL باید از اینترنت عمومی قابل دسترسی باشد؛
- HTTPS و زنجیره گواهی باید معتبر باشند؛
- CDN یا WAF نباید درخواست معتبر سرویس را مسدود کند؛
- مسیر نباید به صفحه ورود، صفحه اصلی یا دامنه دیگری Redirect شود؛
- کش نباید پاسخ ثابت برای Callback بسازد؛
- قوانین امنیتی نباید پارامترهای معتبر سرویس را حذف کنند؛
- تغییر دامنه، مسیر نصب وردپرس یا اجبار
wwwباید در پنل سرویس نیز بازبینی شود؛ - Allowlist کردن IP فقط بر اساس فهرست رسمی و جاری خود سرویس انجام شود.
اگر سرویس هم بازگشت مرورگر و هم درخواست سمت سرور دارد، هر دو باید به مقصد صحیح برسند. موفق‌بودن یکی، سالم‌بودن دیگری را تضمین نمی‌کند.
وضعیت سفارش پس از پرداخت
سفارش پیش از تأیید پرداخت معمولاً در وضعیت «در انتظار پرداخت» قرار دارد. پس از تأیید معتبر سرویس، درگاه فرایند تکمیل پرداخت ووکامرس را اجرا می‌کند؛ سپس ووکامرس با توجه به نوع اقلام، وضعیت مناسب مانند «در حال انجام» یا «تکمیل‌شده» را تعیین می‌کند.
وضعیت نهایی می‌تواند تحت تأثیر محصول دانلودی یا مجازی، مدیریت موجودی، افزونه‌های گردش سفارش و تنظیمات فروشگاه قرار بگیرد. بنابراین انتظار نداشته باشید همه پرداخت‌های موفق الزاماً یک وضعیت واحد داشته باشند.
برای بررسی نتیجه، این موارد را در صفحه سفارش کنترل کنید:
- وضعیت سفارش؛
- روش پرداخت انتخاب‌شده؛
- شناسه تراکنش یا شماره مرجع؛
- یادداشت‌های سفارش؛
- زمان ایجاد، بازگشت و تأیید پرداخت؛
- کاهش موجودی، در صورت فعال‌بودن مدیریت موجودی.
سفارشی را که فقط بر اساس تصویر مشتری یا پیام بازگشت «موفق» به نظر می‌رسد، دستی پرداخت‌شده علامت نزنید. ابتدا پنل سرویس، مبلغ، شناسه مرجع و یادداشت‌های سفارش را تطبیق دهید.
Checkout کلاسیک و بلوکی
درگاه‌های جم پک برای Checkout کلاسیک و بلوک Checkout ووکامرس ثبت می‌شوند. در تسویه‌حساب بلوکی، عنوان، توضیحات، آیکن و وضعیت دسترسی در صفحه مشتری نمایش داده می‌شوند و سرور سایت عملیات پرداخت را انجام می‌دهد.
بااین‌حال، وجود هر دو ساختار در فروشگاه یا تغییر قالب می‌تواند تفاوت‌های ظاهری و تداخلی ایجاد کند. پیش از انتشار:
- درگاه را در صفحه Checkout واقعی فروشگاه بررسی کنید؛
- انتخاب درگاه و نمایش توضیحات را آزمایش کنید؛
- پرداخت مهمان و کاربر واردشده را جداگانه بسنجید؛
- نسخه موبایل را بررسی کنید؛
- اگر هنوز Checkout کلاسیک دارید، یک آزمون جداگانه برای آن انجام دهید؛
- پس از بروزرسانی ووکامرس یا تغییر نوع Checkout، آزمون پرداخت را تکرار کنید.
حالت آزمایشی و تراکنش کنترل‌شده
محیط آزمایشی یا Sandbox در همه درگاه‌ها یکسان نیست. در نسخه بررسی‌شده، زرین‌پال و زیبال تنظیمات آزمایشی مربوط به خود را دارند؛ برای سامان SEP، به‌پرداخت ملت و اسنپ‌پی نباید بدون تأیید سرویس وجود Sandbox را فرض کرد.
هنگام استفاده از حالت آزمایشی:
- اطلاعات آزمایشی را با اطلاعات عملیاتی ترکیب نکنید؛
- نتیجه Sandbox را معادل تأیید نهایی محیط واقعی ندانید؛
- پس از خروج از حالت آزمایشی، اطلاعات حساب را دوباره بررسی کنید؛
- یک تراکنش واقعی کم‌مبلغ و کنترل‌شده نیز پیش از انتشار کامل انجام دهید، اگر قرارداد و سرویس اجازه می‌دهد.
اگر سرویس محیط آزمایشی ارائه نمی‌دهد، با هماهنگی حسابداری و مطابق شرایط سرویس یک خرید کم‌مبلغ واقعی انجام دهید و روش بازگشت وجه یا ابطال آن را از قبل مشخص کنید.
گزارش فنی و یادداشت سفارش
نخستین محل بررسی مشکل، یادداشت‌های همان سفارش است. این یادداشت‌ها می‌توانند مرحله ارسال، بازگشت، تأیید، خطای سرویس یا شناسه تراکنش را نشان دهند.
برای مشاهده گزارش‌های ووکامرس:
- به «ووکامرس ← وضعیت ← گزارش‌ها» بروید.
- منبع مربوط به درگاه و بازه زمانی رخداد را انتخاب کنید.
- زمان سفارش، شناسه سفارش و پاسخ مرتبط را بررسی کنید.
گزینه گزارش فنی در همه درگاه‌ها یکسان نیست؛ بعضی درگاه‌ها سوییچ اختصاصی Debug دارند و بعضی اطلاعات لازم را در یادداشت سفارش یا لاگ مرتبط ثبت می‌کنند. جزئیات در مستند اختصاصی همان درگاه ذکر می‌شود.
گزارش را فقط برای زمان لازم فعال نگه دارید. پیش از ارسال آن برای پشتیبانی، اطلاعات پذیرنده، توکن، رمز، اطلاعات تماس مشتری و داده‌های پرداخت را حذف کنید.
لایسنس و پرداخت‌های در حال انجام
درگاه‌های Pro تنها با دسترسی معتبر برای پرداخت جدید در دسترس قرار می‌گیرند. اگر دسترسی Pro برقرار نباشد، مشتری نباید بتواند پرداخت تازه‌ای را با آن درگاه آغاز کند.
مسیرهای بازگشت فعال می‌مانند تا نتیجه پرداخت‌هایی که قبلاً شروع شده‌اند به سایت برسد. روش پرداخت ثبت‌شده در سفارش‌ها و تراکنش‌های قبلی هم حفظ می‌شود.
هنگام تمدید لایسنس، تغییر اطلاعات پذیرنده، بروزرسانی افزونه یا خاموش‌کردن درگاه، ابتدا مطمئن شوید پرداخت فعالی در جریان نیست. کش و Sessionها را نیز وسط یک آزمون پرداخت پاک نکنید.
چک‌لیست انتقال از آزمایشی به عملیاتی
- دامنه نهایی در قرارداد و پنل پذیرندگی ثبت شده است؛
- SSL دامنه نهایی معتبر است؛
- اطلاعات عملیاتی جایگزین اطلاعات آزمایشی شده است؛
- حالت آزمایشی خاموش شده است؛
- Callback دقیق محیط عملیاتی در پنل سرویس ثبت شده است؛
- واحد پول و مبلغ ارسالی بررسی شده است؛
- Checkout، صفحه پرداخت سفارش و Callback از کش مستثنا هستند؛
- قوانین WAF و فایروال درخواست سرویس را مسدود نمی‌کنند؛
- عنوان و توضیحات درگاه برای مشتری مناسب است؛
- ایمیل‌ها، پیامک‌ها و وضعیت سفارش پس از پرداخت بررسی شده‌اند؛
- یک پرداخت موفق واقعی ثبت و با پنل سرویس تطبیق داده شده است؛
- لغو و پرداخت ناموفق نیز آزمایش شده‌اند؛
- دسترسی به تنظیمات و لاگ‌ها محدود شده است؛
- نسخه پشتیبان سالم پیش از تغییرات مهم وجود دارد.
سناریوهای ضروری آزمون
برای هر درگاه، فقط یک پرداخت موفق کافی نیست. جدول زیر حداقل پوشش پیشنهادی را نشان می‌دهد:
| سناریو | نتیجه مورد انتظار |
|---|---|
| پرداخت موفق | سفارش یک بار تأیید، شناسه تراکنش ثبت و مشتری به نتیجه صحیح هدایت شود |
| لغو توسط مشتری | سفارش پرداخت‌شده نشود و پیام قابل‌فهم نمایش داده شود |
| خطای سرویس یا اطلاعات پذیرنده | سفارش پرداخت‌نشده بماند و خطای قابل پیگیری ثبت شود |
| بازگشت تکراری یا Refresh | سفارش دوباره تأیید و موجودی دوباره کم نشود |
| Callback با تأخیر | نتیجه بدون وابستگی به Session فعال مشتری پردازش شود |
| مبلغ نامنطبق | پرداخت به‌عنوان نتیجه معتبر همان سفارش پذیرفته نشود |
| کاربر مهمان | پرداخت و بازگشت بدون نیاز به ورود انجام شود |
| کاربر واردشده | سفارش در حساب کاربری و تاریخچه درست نمایش داده شود |
| موبایل | رفت‌وبرگشت میان مرورگر یا اپ پرداخت و فروشگاه صحیح باشد |
| Checkout کلاسیک | انتخاب و ارسال سفارش بدون خطای JavaScript انجام شود |
| Checkout بلوکی | درگاه نمایش داده شود و فرایند پرداخت به‌درستی آغاز شود |
| تخفیف، ارسال و مالیات | مبلغ در صفحه سرویس دقیقاً با جمع نهایی سفارش یکسان باشد |
| محصول متغیر | مبلغ، موجودی و اقلام سفارش صحیح ثبت شوند |
| سفارش تکراری | هر تلاش پرداخت با سفارش و شناسه درست تطبیق داده شود |
پس از هر آزمون، نتیجه را هم در ووکامرس و هم در پنل سرویس پرداخت بررسی کنید.
اگر آزمون پرداخت ناموفق بود
نام درگاه، سفارش آزمایشی، مبلغ و مرحله توقف را ثبت کنید. تا وقتی نتیجه تراکنش قبلی روشن نشده است، پرداخت را دوباره اجرا نکنید و وضعیت سفارش را صرفاً از روی رسید مشتری تغییر ندهید.
برای خطاهای نمایش درگاه، انتقال، بازگشت، تأیید، مبلغ و تکرار پردازش، رفع خطاهای پرداخت و تراکنش‌های ناموفق مرجع مشترک است. کدهای سرویس و رفتار اختصاصی تأیید، تسویه یا بازپرداخت را در راهنمای همان درگاه بررسی کنید.
آموزش‌های مرتبط
- راه‌اندازی درگاه پرداخت زرین‌پال ووکامرس
- راه‌اندازی درگاه پرداخت زیبال ووکامرس
- راه‌اندازی درگاه پرداخت سامان SEP ووکامرس
- راه‌اندازی درگاه پرداخت به‌پرداخت ملت ووکامرس
- راه‌اندازی پرداخت اقساطی اسنپ‌پی ووکامرس
- آشنایی با محیط جم پک و مدیریت ماژول‌ها