راه‌اندازی پرداخت اقساطی اسنپ‌پی ووکامرس

درگاه اسنپ‌پی جم پک، امکان خرید اعتباری و اقساطی را به Checkout ووکامرس اضافه می‌کند. در الگوی رایج این سرویس، مشتری یک‌چهارم مبلغ را هنگام خرید و سه قسط بعدی را در ماه‌های آینده می‌پردازد؛ بااین‌حال، مبلغ مجاز، وضعیت اعتبار مشتری، گروه کالایی و شرایط نهایی هر خرید را اسنپ‌پی تعیین می‌کند.

پیش از نمایش اسنپ‌پی، سرویس بررسی می‌کند مبلغ سبد برای پرداخت اقساطی مجاز است یا نه؛ این بررسی Eligibility نام دارد. برای شروع پرداخت، سایت توکن دسترسی (OAuth Token) می‌گیرد و اطلاعات سبد را می‌فرستد. پس از بازگشت مشتری، تأیید تراکنش (Verify) و نهایی‌کردن دریافت آن (Settle) انجام می‌شوند.

فرایند کلی به این صورت است:

1. فروشگاه با چهار مشخصه اتصال دریافتی از اسنپ‌پی، توکن دسترسی می‌گیرد.
2. اسنپ‌پی واجدشرایط‌بودن مبلغ سبد را بررسی می‌کند.
3. فروشگاه جزئیات سفارش را ارسال و paymentToken و paymentPageUrl دریافت می‌کند.
4. مشتری به صفحه پرداخت اسنپ‌پی منتقل می‌شود.
5. اسنپ‌پی مشتری را با وضعیت پرداخت به Callback فروشگاه بازمی‌گرداند.
6. تراکنش ابتدا Verify و سپس Settle می‌شود.
7. فقط پس از Settle موفق، سفارش در ووکامرس پرداخت‌شده محسوب می‌شود.

این قابلیت در سطح Pro قرار دارد و برای آغاز پرداخت جدید به لایسنس معتبر جم پک، قرارداد فعال اسنپ‌پی و اطلاعات دسترسی API نیاز دارد.

این راهنما چه مواردی را پوشش می‌دهد؟

• دریافت و ثبت اطلاعات اتصال اسنپ‌پی؛
• تشخیص IP خروجی سرور و خطای RBAC؛
• انتخاب API واقعی یا Stage؛
• مدیریت تعارض با افزونه رسمی اسنپ‌پی؛
• بررسی Eligibility و علت ناپدیدشدن روش پرداخت؛
• ساخت OAuth Token و رفتار Retry؛
• ارسال مبلغ، کالاها، مالیات، ارسال و تخفیف؛
• تنظیم کمیسیون دسته و برچسب محصول؛
• انتقال مستقیم یا صفحه تأیید اختیاری؛
• Callback، Verify و Settle؛
• رفتار سفارش در حالت نامشخص؛
• Cancel خودکار هنگام لغو یا بازپرداخت کامل سفارش؛
• نمایش مبلغ هر قسط در صفحه محصول؛
• استفاده از شورت‌کد در Bricks و Elementor؛
• ثبت و پاک‌سازی گزارش‌های فنی؛
• آزمون کامل پیش از فعال‌سازی عمومی.

برای تنظیمات عمومی HTTPS، کش، Callback و وضعیت سفارش، ابتدا تنظیمات مشترک درگاه‌های پرداخت ووکامرس را مطالعه کنید.

دریافت اطلاعات اتصال از اسنپ‌پی

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

فیلد	عنوان قراردادی متداول	کاربرد
Client ID	شماره مشتری	ساخت Basic Authorization
Client Secret	کد امنیتی مشتری	ساخت Basic Authorization
Username	نام کاربری خرید	OAuth Password Grant
Password	رمز عبور خرید	OAuth Password Grant

نام کاربری و رمز خرید را با اطلاعات ورود پنل گزارش‌گیری اشتباه نگیرید. هر چهار مقدار باید متعلق به یک محیط و یک پذیرنده باشند.

اگر اسنپ‌پی آدرس و اطلاعات محیط آزمایشی (Stage) را داده است، از همه مشخصات همان محیط استفاده کنید. اطلاعات اتصال آزمایشی را با آدرس API واقعی ترکیب نکنید.

IP خروجی سرور

اسنپ‌پی دسترسی API را براساس IP خروجی سرور محدود می‌کند. IP موردنیاز لزوماً IP دامنه، CDN، کامپیوتر مدیر یا بازدیدکننده نیست؛ باید IP عمومی‌ای ثبت شود که درخواست‌های خروجی PHP از طریق آن به API می‌رسند.

نسخه بررسی‌شده از سرویس زیر برای تشخیص IP از دید اسنپ‌پی استفاده می‌کند:

https://whatisip.snapppay.ir/whatis/ip

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

خطای رایج IP ثبت‌نشده معمولاً با HTTP 403 یا پیام زیر دیده می‌شود:

RBAC: access denied

در متن خطای نسخه بررسی‌شده اعلام شده است که اسنپ‌پی حداکثر سه IP را می‌پذیرد. این محدودیت را با شرایط جاری قرارداد خود تأیید کنید.

پس از تغییر هاست، دیتاسنتر، NAT، Proxy یا شبکه خروجی، IP را دوباره بررسی و در اسنپ‌پی ثبت کنید.

ورود به تنظیمات اسنپ‌پی

برای پیکربندی:

1. وارد پیشخوان وردپرس شوید.
2. از منوی جم پک، «درگاه‌های پرداخت» را انتخاب کنید.
3. پنل «اسنپ‌پی» را باز کنید.
4. تنظیمات پایه، حساب، عملیات و ویجت محصول را تکمیل کنید.
5. تغییرات را ذخیره کنید.

نشانی صفحه تنظیمات:

/wp-admin/admin.php?page=gempack#payment-gateways

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

تعارض با افزونه رسمی اسنپ‌پی

نباید افزونه رسمی «SnappPay Woocommerce Gateway» و درگاه اسنپ‌پی جم پک هم‌زمان فعال باشند. اگر دو افزونه عملیات پرداخت یک پذیرنده را مدیریت کنند، ممکن است این مشکلات رخ دهند:

• نمایش دو روش پرداخت اسنپ‌پی؛
• اجرای دو درخواست Cancel برای یک تغییر وضعیت؛
• اختلاف Callback ثبت‌شده با Handler فعال؛
• تلاش هم‌زمان برای Verify یا Settle؛
• وضعیت مالی ناسازگار میان سفارش و پنل.

اگر افزونه رسمی فعال باشد، جم پک:

• درگاه داخلی خود را غیرقابل‌استفاده می‌کند؛
• سوییچ فعال‌سازی را قفل می‌کند؛
• هشدار مدیریتی نمایش می‌دهد؛
• تنظیمات ذخیره‌شده را حذف نمی‌کند؛
• مسیر بازگشت افزونه رسمی را برای درگاه داخلی خود فعال نمی‌کند.

برای مهاجرت:

1. سفارش‌های در حال پرداخت را بررسی کنید.
2. از تنظیمات و شناسه‌های لازم نسخه پشتیبان بگیرید.
3. افزونه رسمی را غیرفعال کنید.
4. درگاه جم پک را فعال کنید.
5. یک پرداخت جدید و یک سفارش قدیمی کنترل‌شده را بررسی کنید.

جم پک چند کلید قدیمی Token افزونه رسمی را می‌خواند تا سفارش در حال پرداخت پس از مهاجرت نیز قابل Verify باشد. افزونه Searchwise فید محصول تعارض محسوب نمی‌شود.

تنظیمات پایه

فعال‌سازی درگاه اسنپ‌پی

سوییچ فعال‌سازی، امکان حضور اسنپ‌پی در Checkout را فراهم می‌کند. فعال‌بودن سوییچ به‌تنهایی به معنی نمایش همیشگی درگاه نیست؛ هر مبلغ باید از Eligibility عبور کند.

درگاه فقط زمانی قابل استفاده است که:

• افزونه رسمی اسنپ‌پی فعال نباشد؛
• هر چهار مشخصه اتصال وارد شده باشند؛
• درگاه فعال باشد؛
• لایسنس و شرایط پایه برقرار باشند؛
• پاسخ Eligibility مبلغ، مثبت باشد.

عنوان درگاه

عنوان پیش‌فرض:

پرداخت اقساطی اسنپ‌پی

اسنپ‌پی می‌تواند برای سبد واجدشرایط، title_message خود را برگرداند. در این حالت عنوان API جای متن ثابت تنظیمات را در Checkout می‌گیرد.

توضیحات درگاه

توضیح پیش‌فرض نیز «پرداخت اقساطی اسنپ‌پی» است. پاسخ Eligibility می‌تواند توضیح اختصاصی سرویس را جایگزین این متن کند.

نمونه مناسب در صورت استفاده از متن ثابت:

مبلغ سفارش را در چهار قسط پرداخت کنید؛ تأیید نهایی براساس اعتبار و شرایط اسنپ‌پی انجام می‌شود.

عبارت‌های «تضمین اعتبار» یا «قابل استفاده برای همه» را به کار نبرید.

تنظیمات حساب اسنپ‌پی

آدرس API

مقدار پیش‌فرض نسخه بررسی‌شده:

https://api.snapppay.ir/

این مقدار را فقط زمانی تغییر دهید که اسنپ‌پی آدرس Stage یا Endpoint دیگری را رسماً در سند دسترسی ارائه کرده باشد. واردکردن آدرس نامطمئن باعث ارسال اعتبارنامه و اطلاعات سفارش به مقصد نادرست می‌شود.

Client ID و Client Secret

این دو مقدار برای Basic Authorization درخواست OAuth استفاده می‌شوند. هر دو را دقیقاً از سند دسترسی بردارید و فاصله ابتدا یا انتها را حذف کنید.

نام کاربری و رمز خرید

این دو مقدار با grant_type=password و Scope زیر برای ساخت OAuth Token ارسال می‌شوند:

online-merchant

اگر یکی از چهار فیلد خالی باشد، درگاه در Checkout قابل استفاده نخواهد بود.

احراز هویت OAuth

پیش از Eligibility یا عملیات پرداخت، فروشگاه Access Token دریافت می‌کند. Token تا نزدیک زمان انقضا کش می‌شود و یک دقیقه زودتر از زمان اعلام‌شده منقضی در نظر گرفته می‌شود تا در میانه درخواست اعتبار خود را از دست ندهد.

اگر API پاسخ 401 بدهد، جم پک:

1. Token کش‌شده را حذف می‌کند؛
2. یک Token تازه می‌گیرد؛
3. همان درخواست را فقط یک بار تکرار می‌کند.

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

اگر یکی از چهار مشخصه اتصال یا آدرس API را تغییر دهید، توکن و پاسخ‌های ذخیره‌شده بررسی شرایط مبلغ، برای اتصال جدید استفاده نمی‌شوند.

تنظیمات عملیات پرداخت

انتخاب پیش‌فرض در Checkout

اگر «انتخاب پیش‌فرض» فعال باشد، اسنپ‌پی برای سبد واجدشرایط به‌صورت انتخاب‌شده نمایش داده می‌شود.

این گزینه:

• Eligibility را دور نمی‌زند؛
• مشتری را مجبور به استفاده از اسنپ‌پی نمی‌کند؛
• درگاه را برای مبلغ نامعتبر نمایش نمی‌دهد؛
• اعتبار مشتری را تضمین نمی‌کند.

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

صفحه تأیید پیش از انتقال

این گزینه به‌صورت پیش‌فرض خاموش است.

• خاموش: مشتری پس از ثبت سفارش مستقیماً به paymentPageUrl اسنپ‌پی می‌رود.
• روشن: ابتدا صفحه پرداخت سفارش در سایت نمایش داده می‌شود و مشتری با دکمه «پرداخت با اسنپ‌پی» ادامه می‌دهد.

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

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

ارسال شماره موبایل مشتری

این گزینه به‌صورت پیش‌فرض روشن است. شماره صورت‌حساب برای شناسایی مشتری بازگشتی به اسنپ‌پی ارسال می‌شود و در متای جداگانه‌ای توسط این قابلیت ذخیره نمی‌شود.

شماره‌های فارسی، عربی یا لاتین ابتدا به رقم لاتین تبدیل می‌شوند. قالب‌های رایج زیر پذیرفته می‌شوند:

09121234567
989121234567
00989121234567

خروجی API:

+989121234567

اگر پس از نرمال‌سازی، شماره ده رقم و شروع‌شونده با 9 نباشد، ارسال نمی‌شود.

ارسال موبایل را در سیاست حریم خصوصی فروشگاه توضیح دهید. این داده به‌تنهایی Eligibility یا مالکیت اعتبار را ثابت نمی‌کند.

پیام موفق

در پیام موفق می‌توانید از این جای‌نگهدار استفاده کنید:

{transaction_id}

در نسخه بررسی‌شده، این مقدار با paymentToken جایگزین می‌شود. چون Token می‌تواند داده فنی حساس باشد، بهتر است آن را در پیام عمومی مشتری قرار ندهید و از متن ساده زیر استفاده کنید:

پرداخت اقساطی سفارش با موفقیت تأیید شد.

پیام ناموفق

جای‌نگهدار زیر علت گزارش‌شده را نشان می‌دهد:

{fault}

نمونه:

پرداخت تکمیل نشد: {fault} لطفاً روش دیگری را انتخاب کنید یا با پشتیبانی تماس بگیرید.

پیام انصراف

این پیام برای وضعیت‌های CANCELED و CANCELLED Callback استفاده می‌شود.

نمونه:

پرداخت به‌دلیل انصراف شما تکمیل نشد. می‌توانید دوباره تلاش کنید یا روش دیگری را انتخاب کنید.

ثبت گزارش فنی

گزینه Debug، درخواست‌ها و پاسخ‌های کامل را در گزارش ووکامرس با منبع زیر ثبت می‌کند:

aio-wc-snappay

خطاها حتی با Debug خاموش نیز ثبت می‌شوند. گزارش کامل را فقط برای عیب‌یابی کوتاه‌مدت روشن کنید.

گزارش تفصیلی ممکن است توکن کامل را نشان دهد. پاسخ ساخت پرداخت می‌تواند شامل paymentToken و paymentPageUrl باشد. حتی اگر در رابط گفته شده توکن پوشانده می‌شود، همه خطوط گزارش را پیش از اشتراک‌گذاری بررسی کنید.

پس از رفع مشکل:

1. Debug را خاموش کنید.
2. گزارش‌های ساخته‌شده را پاک‌سازی کنید.
3. پیش از ارسال گزارش، Token، URL پرداخت، موبایل و اطلاعات سفارش را حذف کنید.

بررسی Eligibility سبد

اسنپ‌پی برای هر مبلغ مشخص می‌کند آیا روش اقساطی باید ارائه شود یا نه. جم پک مبلغ نهایی Checkout را به ریال تبدیل و Endpoint Eligibility را فراخوانی می‌کند.

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

• بازخوانی Checkout با مبلغ ثابت، درخواست تکراری غیرضروری نمی‌سازد؛
• تغییر تعداد، تخفیف یا هزینه ارسال و در نتیجه تغییر مبلغ، بررسی تازه‌ای ایجاد می‌کند؛
• تغییر اعتبارنامه، پاسخ کش‌شده محیط قبلی را بی‌اعتبار می‌کند.

اگر پاسخ eligible=false باشد، روش اسنپ‌پی از Checkout حذف می‌شود.

اگر API به‌دلیل شبکه، اعتبارنامه یا IP قابل پرسش نباشد:

• روش برای مشتریان عادی مخفی می‌شود تا وارد مسیر خراب نشوند؛
• مدیر دارای دسترسی مدیریت ووکامرس می‌تواند درگاه را همراه علت خطا ببیند؛
• آخرین خطا برای ۱۵ دقیقه نگه داشته و در صفحه تنظیمات به‌صورت هشدار نمایش داده می‌شود؛
• خطای شبکه به‌عنوان «واجدشرایط نیست» برای پنج دقیقه کش نمی‌شود.

Eligibility مبلغ به معنی تأیید نهایی مشتری نیست. اسنپ‌پی پس از انتقال، حساب و اعتبار مشتری را نیز بررسی می‌کند.

داده‌های ارسالی سفارش

هنگام ساخت Token پرداخت، اطلاعات زیر ارسال می‌شوند:

• مبلغ کل سفارش به ریال؛
• نوع پرداخت INSTALLMENT؛
• Callback فروشگاه؛
• Transaction ID یکتای تلاش؛
• فهرست کالاها؛
• مبلغ تخفیف؛
• موبایل، در صورت فعال و معتبر بودن.

برای هر کالا نیز این اطلاعات ساخته می‌شوند:

• شناسه محصول یا وارییشن؛
• نام محصول؛
• تعداد؛
• قیمت واحد به ریال؛
• نام دسته محصول؛
• Commission Type، در صورت فعال‌بودن.

قیمت آیتم، قیمت واحد است و تعداد جداگانه ارسال می‌شود. اطلاعات سبد شامل مالیات، هزینه ارسال و وضعیت حضور این دو نیز هست.

Transaction ID هر تلاش از شناسه سفارش و زمان ساخته می‌شود؛ بنابراین تلاش دوباره همان سفارش به‌عنوان تراکنش مستقل شناخته می‌شود.

تنظیم کمیسیون دسته و برچسب

گزینه «ارسال نوع کمیسیون برای دسته و برچسب» فقط زمانی لازم است که قرارداد اسنپ‌پی برای گروه‌های کالایی مختلف Commission Type متفاوتی تعیین کرده باشد.

با فعال‌کردن این گزینه، فیلد «نوع کمیسیون اسنپ‌پی» به صفحه افزودن و ویرایش موارد زیر اضافه می‌شود:

• دسته محصولات؛
• برچسب محصولات.

مقدار باید شماره‌ای باشد که اسنپ‌پی برای گروه اعلام کرده است. ارقام فارسی و عربی به لاتین تبدیل و نویسه‌های غیرعددی حذف می‌شوند.

ترتیب انتخاب مقدار، از خاص به عمومی است:

1. برچسب خود محصول؛
2. عمیق‌ترین دسته محصول؛
3. والدهای همان دسته تا سطح ریشه.

وارییشن مقدار را از محصول مادر می‌گیرد. اگر فیلد دسته فرزند خالی باشد، مقدار دسته والد قابل ارث‌بری است.

کلید فنی ذخیره‌سازی با افزونه رسمی سازگار است:

snp_commission_type

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

ایجاد Token پرداخت

پس از ثبت سفارش، درخواست ساخت Token ارسال می‌شود. پاسخ موفق باید حداقل این دو مقدار را داشته باشد:

• paymentToken؛
• paymentPageUrl.

جم پک Token، Transaction ID، مبلغ ریالی و URL صفحه پرداخت را روی سفارش ذخیره می‌کند. در یادداشت اولیه فقط نسخه ماسک‌شده Token نوشته می‌شود.

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

Callback اسنپ‌پی

Callback به‌صورت خودکار از Endpoint ووکامرس و شناسه سفارش ساخته می‌شود. ساختار آن مشابه زیر است:

https://example.com/?wc-api=aio_wc_snappay&wc_order=123

برای سازگاری با فروشگاه‌هایی که از افزونه رسمی مهاجرت می‌کنند، در صورت غیرفعال‌بودن آن افزونه، Endpoint زیر نیز پاسخ داده می‌شود:

wc_gateway_snapppay

این نام جایگزین کمک می‌کند نشانی بازگشت قدیمی، پس از مهاجرت همچنان کار کند.

Callback می‌تواند با POST یا GET دریافت شود، اما سفارش از wc_order موجود در URL پیدا می‌شود. Query String نباید در Redirect، CDN یا WAF حذف شود.

وضعیت بازگشت

تنها وضعیت زیر اجازه ورود به Verify را می‌دهد:

OK

اگر وضعیت CANCELED یا CANCELLED باشد، پیام انصراف نمایش داده می‌شود. وضعیت‌های دیگر پرداخت ناموفق تلقی و روی سفارش ذخیره می‌شوند.

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

Verify و Settle

پس از state=OK، Token ذخیره‌شده سفارش برای Verify ارسال می‌شود.

شکست یا ابهام Verify

اگر Verify با خطای شبکه روبه‌رو شود یا پاسخ successful نداشته باشد:

• سفارش Fail نمی‌شود؛
• وضعیت سفارش به «در انتظار بررسی» (on-hold) می‌رود؛
• علت در یادداشت و گزارش ثبت می‌شود؛
• پیام «در انتظار تأیید» به مشتری نشان داده می‌شود؛
• کالا یا دسترسی نباید تحویل شود.

ممکن است اسنپ‌پی پرداخت را مجاز کرده باشد (Authorised)، اما نتیجه نهایی هنوز مشخص نباشد. آن را از پنل بررسی و تعیین تکلیف کنید.

Settle بعد از Verify

Verify مجوز پرداخت را تأیید می‌کند، اما Settle دریافت آن را نهایی می‌سازد. فقط پس از پاسخ موفق Settle:

• حالت داخلی سفارش SETTLE می‌شود؛
• paymentToken به‌عنوان Transaction ID ووکامرس ذخیره می‌شود؛
• payment_complete() اجرا می‌شود؛
• موجودی و وضعیت سفارش طبق قواعد ووکامرس بروزرسانی می‌شوند؛
• سبد مشتری خالی می‌شود؛
• پیام موفق نمایش داده می‌شود.

شکست Settle

اگر Verify موفق و Settle ناموفق باشد:

• سفارش on-hold می‌شود؛
• payment_complete() اجرا نمی‌شود؛
• سفارش پرداخت‌شده تلقی نمی‌شود؛
• مدیر باید از پنل اسنپ‌پی Settle یا Cancel را انجام دهد؛
• سپس وضعیت سفارش را مطابق نتیجه مالی اصلاح کند.

در این حالت وجه ممکن است فقط Authorised باشد و هنوز از مشتری دریافت نشده باشد. سفارش را تا تعیین تکلیف ارسال نکنید.

لغو و بازپرداخت سفارش

نسخه بررسی‌شده متد استاندارد process_refund() ووکامرس برای Refund جزئی ندارد. در عوض، وقتی وضعیت سفارش به یکی از این دو حالت تغییر کند، Endpoint Cancel اسنپ‌پی فراخوانی می‌شود:

• cancelled؛
• refunded.

این رفتار باعث می‌شود مشتری بابت سفارش لغوشده همچنان اقساط پرداخت نکند، اما تغییر وضعیت سفارش یک عملیات مالی واقعی محسوب می‌شود.

پیش از تغییر وضعیت:

1. سفارش و paymentToken را بررسی کنید.
2. سیاست بازگشت کالا و مبلغ را کنترل کنید.
3. مشخص کنید لغو کامل طرح اقساطی موردنظر است.
4. نتیجه Cancel را در یادداشت سفارش و پنل اسنپ‌پی ببینید.

اگر Cancel موفق باشد، متای سفارش با مقدار yes علامت‌گذاری می‌شود تا درخواست موفق دوباره ارسال نشود.

اگر Cancel ناموفق باشد:

• سفارش ممکن است در ووکامرس لغوشده یا بازپرداخت‌شده باشد؛
• اما طرح اقساطی در اسنپ‌پی همچنان فعال بماند؛
• یادداشت هشدار به سفارش اضافه می‌شود؛
• باید فوراً عملیات را از پنل اسنپ‌پی انجام دهید.

تغییر دستی وضعیت به refunded را جای اجرای فرایند مالی صحیح ندانید. برای Refund جزئی یا سناریویی که نیاز به حفظ بخشی از سفارش دارد، ابتدا رویه رسمی اسنپ‌پی را از پنل یا پشتیبانی دنبال کنید.

ویجت مبلغ اقساط در صفحه محصول

ویجت محصول، مبلغ تقریبی هر یک از چهار قسط را زیر قیمت نمایش می‌دهد. این عدد از قیمت موجود در صفحه محاسبه می‌شود و درخواست Eligibility زنده به اسنپ‌پی ارسال نمی‌کند؛ بنابراین خرابی API باعث کندی صفحه محصول نمی‌شود.

متن ویجت، به‌صورت مفهومی این اطلاعات را نشان می‌دهد:

مبلغ هر قسط با اسنپ‌پی: ۲٬۵۰۰٬۰۰۰ تومان
۴ قسط ماهانه؛ بدون سود، چک و ضامن

این نمایش فقط برآورد قیمت محصول است. تخفیف سبد، حمل‌ونقل، مالیات، Eligibility مبلغ و اعتبار مشتری در Checkout تعیین می‌شوند.

حداقل و حداکثر نمایش

دو فیلد حداقل و حداکثر مشخص می‌کنند ویجت برای چه قیمت‌هایی دیده شود. این مقدارها با واحد پول خود فروشگاه وارد می‌شوند، نه ریال اجباری API.

مقادیر پیش‌فرض نسخه بررسی‌شده:

حداقل: 50000
حداکثر: 100000000

این اعداد فقط محدوده نمایش ویجت را تعیین می‌کنند و شرایط واقعی پذیرش مبلغ را تغییر نمی‌دهند. محدوده را مطابق قرارداد و واحد پول سایت بروزرسانی کنید.

محصول متغیر

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

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

لوگوی اسنپ‌پی

می‌توانید URL لوگویی را وارد کنید که قبلاً در کتابخانه رسانه سایت بارگذاری شده است. اگر فیلد خالی باشد، ویجت متنی نمایش داده می‌شود.

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

استفاده در Bricks و Elementor

در قالب استاندارد ووکامرس، ویجت با اولویت ۱۱ بلافاصله بعد از قیمت قرار می‌گیرد. صفحه‌سازهایی مانند Bricks و Elementor ممکن است Hook استاندارد خلاصه محصول را اجرا نکنند؛ در این حالت از شورت‌کد زیر استفاده کنید:

[aio_wc_snappay_instalments]

در قالب Single Product، شورت‌کد محصول جاری را خودکار تشخیص می‌دهد. برای محصول مشخص نیز می‌توان شناسه را فرستاد:

[aio_wc_snappay_instalments id="123"]

اگر ویجت خودکار و شورت‌کد هر دو در یک صفحه اجرا شوند، خروجی برای هر محصول فقط یک بار نمایش داده می‌شود.

گزارش‌های ووکامرس

برای مشاهده گزارش:

1. به «ووکامرس ← وضعیت ← گزارش‌ها» بروید.
2. منبعی با نام aio-wc-snappay را انتخاب کنید.
3. زمان سفارش یا درخواست را پیدا کنید.
4. Eligibility، OAuth، Token، Callback، Verify، Settle یا Cancel را بررسی کنید.

سطوح مهم:

• خطاهای ارتباط و عملیات با سطح Error همیشه ثبت می‌شوند؛
• جزئیات Info و پاسخ خام فقط با Debug روشن ثبت می‌شوند؛
• Token در بعضی یادداشت‌ها ماسک می‌شود، اما پاسخ خام Debug می‌تواند Token کامل داشته باشد.

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

گزارش را بدون پاک‌سازی برای پشتیبانی نفرستید.

آزمون کامل پیش از انتشار

سبد واجدشرایط

1. یک سبد با مبلغ مجاز بسازید.
2. Checkout را بدون Cache باز کنید.
3. نمایش عنوان و توضیح بازگشتی اسنپ‌پی را بررسی کنید.
4. روش پرداخت را انتخاب و سفارش را ثبت کنید.
5. انتقال به paymentPageUrl را کنترل کنید.
6. پرداخت را تکمیل کنید.
7. Callback، Verify و Settle را بررسی کنید.
8. Transaction ID و یادداشت سفارش را با پنل تطبیق دهید.

سبد غیرواجدشرایط

مبلغی خارج از محدوده قراردادی بسازید. روش اسنپ‌پی باید از Checkout حذف شود و سایر روش‌ها در دسترس بمانند.

تغییر مبلغ سبد

تعداد کالا، کد تخفیف یا روش ارسال را تغییر دهید. Eligibility باید براساس مبلغ جدید بررسی شود.

IP ثبت‌نشده

فقط در محیط کنترل‌شده، نتیجه 403 یا RBAC را بررسی کنید. مشتری عادی نباید درگاه خراب را ببیند و مدیر باید علت را مشاهده کند.

انصراف مشتری

در صفحه اسنپ‌پی انصراف دهید. سفارش نباید پرداخت‌شده شود و پیام انصراف باید قابل‌فهم باشد.

Callback تکراری

صفحه بازگشت موفق را دوباره باز کنید. Verify، Settle و کاهش موجودی نباید دوباره اجرا شوند.

Settle ناموفق کنترل‌شده

اگر محیط Stage امکان شبیه‌سازی دارد، شکست Settle را بررسی کنید. سفارش باید on-hold بماند و payment_complete() اجرا نشود.

لغو مالی

با سفارش کاملاً آزمایشی، وضعیت Cancelled را اعمال و نتیجه Endpoint Cancel را در پنل اسنپ‌پی بررسی کنید. این آزمون را روی سفارش واقعی مشتری انجام ندهید.

ویجت محصول

محصول ساده، متغیر، فروش ویژه، قیمت خارج از محدوده و قالب موبایل را آزمایش کنید. در Bricks یا Elementor نیز شورت‌کد را جداگانه کنترل کنید.

چک‌لیست راه‌اندازی

• [ ] قرارداد و پذیرنده اسنپ‌پی فعال است.
• [ ] Client ID و Client Secret صحیح هستند.
• [ ] نام کاربری و رمز مخصوص خرید ثبت شده‌اند.
• [ ] API واقعی یا Stage با اعتبارنامه همان محیط هماهنگ است.
• [ ] IP خروجی سرور نزد اسنپ‌پی ثبت شده است.
• [ ] افزونه رسمی اسنپ‌پی هم‌زمان فعال نیست.
• [ ] HTTPS، DNS و اتصال پورت ۴۴۳ سالم هستند.
• [ ] Checkout و Callback از کش مستثنا شده‌اند.
• [ ] واحد پول و مبلغ ریالی آزمایش شده‌اند.
• [ ] Eligibility برای دو مبلغ مجاز و غیرمجاز بررسی شده است.
• [ ] انتقال مستقیم یا صفحه تأیید انتخاب شده است.
• [ ] تصمیم ارسال موبایل با سیاست حریم خصوصی هماهنگ است.
• [ ] تنظیم کمیسیون فقط در صورت نیاز قرارداد فعال شده است.
• [ ] پرداخت موفق تا Settle کامل آزمایش شده است.
• [ ] Verify و Settle نامشخص برای تیم پشتیبانی رویه مشخص دارند.
• [ ] رفتار Cancel هنگام وضعیت Cancelled و Refunded شناخته شده است.
• [ ] Debug پس از آزمون خاموش شده است.
• [ ] گزارش‌های دارای Token پاک‌سازی شده‌اند.
• [ ] ویجت محصول در قالب و صفحه‌ساز آزمایش شده است.
• [ ] متن صفحه محصول Eligibility قطعی را وعده نمی‌دهد.

عیب‌یابی

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

اسنپ‌پی در Checkout نمایش داده نمی‌شود

• فعال‌بودن درگاه و لایسنس Pro را بررسی کنید؛
• وجود هر چهار اعتبار را کنترل کنید؛
• افزونه رسمی اسنپ‌پی را غیرفعال کنید؛
• مبلغ سبد را تغییر دهید و Eligibility را دوباره بررسی کنید؛
• خطای اخیر تنظیمات را ببینید؛
• منبع aio-wc-snappay را بررسی کنید؛
• برای کاربر مدیر، توضیح نمایش‌داده‌شده کنار درگاه را بخوانید؛
• کش Checkout را پاک کنید.

خطای RBAC یا HTTP 403 دیده می‌شود

• IP خروجی را از سرویس تشخیص یا شرکت هاست بگیرید؛
• آن را با IP دامنه اشتباه نگیرید؛
• IP را برای پذیرنده ثبت کنید؛
• محدودیت تعداد IP را از اسنپ‌پی بپرسید؛
• پس از تأیید، دوباره Eligibility را اجرا کنید؛
• اگر هشدار مدیریتی تا ۱۵ دقیقه باقی ماند، کش Transient را فقط با روش امن و آگاهانه پاک کنید یا منتظر انقضا بمانید.

خطای 401 یا رد اعتبارنامه دریافت می‌شود

• Client ID و Secret را با سند دسترسی تطبیق دهید؛
• نام کاربری خرید را با حساب گزارش‌گیری اشتباه نگیرید؛
• رمز را دوباره وارد کنید؛
• محیط Stage و Production را مخلوط نکنید؛
• در صورت تغییر رمز، یک درخواست تازه اجرا کنید؛
• فاصله و نویسه‌های کپی‌شده را حذف کنید.

Eligibility درگاه را مخفی می‌کند

اگر API پاسخ معتبر eligible=false داده باشد، مبلغ یا شرایط سبد مجاز نیستند. این با خطای اتصال تفاوت دارد.

• مبلغ نهایی ریالی را بررسی کنید؛
• تخفیف، ارسال و مالیات را کنترل کنید؛
• گروه کالا و Commission Type را با قرارداد تطبیق دهید؛
• شرایط جاری پذیرنده را از پنل بررسی کنید؛
• روش پرداخت جایگزین را برای مشتری نگه دارید.

Token ساخته نمی‌شود

• OAuth و خطاهای 401 یا 403 را بررسی کنید؛
• وجود paymentToken و paymentPageUrl در پاسخ را کنترل کنید؛
• جزئیات کالا، قیمت و تعداد را بررسی کنید؛
• مبلغ تخفیف و جمع سبد را تطبیق دهید؛
• Callback و Transaction ID را ببینید؛
• پاسخ خام Debug را فقط در محیط کنترل‌شده بررسی کنید.

صفحه تأیید پیام انقضای جلسه نشان می‌دهد

URL صفحه پرداخت روی سفارش ذخیره نشده یا Token ساخت موفقی نداشته است. یادداشت سفارش و پاسخ Token را بررسی و پرداخت را با تلاش تازه آغاز کنید.

Callback سفارش را پیدا نمی‌کند

• وجود wc_order در URL را بررسی کنید؛
• Redirectهای دامنه را کنترل کنید؛
• WAF و افزونه امنیتی را بررسی کنید؛
• Callback را پشت ورود اجباری قرار ندهید؛
• Alias افزونه رسمی و وضعیت تعارض را بررسی کنید؛
• Token سفارش را بدون انتشار عمومی کنترل کنید.

سفارش روی on-hold مانده است

یادداشت سفارش مشخص می‌کند Verify یا Settle ناموفق بوده است.

• paymentToken را در پنل اسنپ‌پی جست‌وجو کنید؛
• وضعیت Authorised یا Settled را کنترل کنید؛
• در Verify نامشخص، تراکنش را تعیین تکلیف کنید؛
• در Settle ناموفق، از پنل Settle یا Cancel را انجام دهید؛
• فقط پس از نتیجه قطعی، وضعیت سفارش را تغییر دهید.

سفارش Refunded است اما اقساط ادامه دارند

درخواست Cancel ناموفق بوده یا وضعیت فقط در ووکامرس تغییر کرده است.

• یادداشت Cancel سفارش را بررسی کنید؛
• منبع گزارش اسنپ‌پی را ببینید؛
• عملیات Cancel را فوراً از پنل اسنپ‌پی انجام دهید؛
• نتیجه را با مشتری و امور مالی هماهنگ کنید؛
• صرف وضعیت ووکامرس را مدرک لغو اقساط ندانید.

مبلغ اقساط صفحه محصول اشتباه است

• واحد پول فروشگاه را بررسی کنید؛
• قیمت فروش ویژه و وارییشن انتخاب‌شده را کنترل کنید؛
• حداقل و حداکثر ویجت را با واحد خود فروشگاه وارد کنید؛
• کش محصول و صفحه‌ساز را پاک کنید؛
• وجود دو شورت‌کد یا ویجت سفارشی دیگر را بررسی کنید.

ویجت در Bricks یا Elementor دیده نمی‌شود

• سوییچ ویجت را فعال کنید؛
• فعال‌بودن خود درگاه را بررسی کنید؛
• شورت‌کد را در عنصر مناسب قرار دهید؛
• قیمت محصول را با بازه حداقل و حداکثر مقایسه کنید؛
• برای قالب Query Loop، شناسه محصول را درست ارسال کنید؛
• خروجی را خارج از محیط Builder نیز ببینید.

گزارش Debug اطلاعات زیادی دارد

Debug را خاموش و فایل گزارش را پاک کنید. پیش از اشتراک‌گذاری، paymentToken، URL پرداخت، موبایل، شناسه سفارش و پاسخ خام را حذف کنید.

نکات امنیتی و عملیاتی

• چهار اعتبار اتصال را فقط در اختیار مدیران مجاز قرار دهید؛
• آدرس API را بدون سند رسمی تغییر ندهید؛
• اعتبارنامه واقعی را در سایت Stage نامطمئن کپی نکنید؛
• SSL Verification را برای رفع خطای اتصال غیرفعال نکنید؛
• IP خروجی را پس از هر مهاجرت دوباره ثبت کنید؛
• Token OAuth و paymentToken را در تیکت عمومی منتشر نکنید؛
• یادداشت مشتری سفارش را نیز پیش از اشتراک‌گذاری بررسی کنید، زیرا نسخه فعلی Token کامل را پس از Settle در آن می‌نویسد؛
• از {transaction_id} در پیام عمومی موفق استفاده نکنید؛
• Debug را کوتاه‌مدت روشن و سپس گزارش‌ها را حذف کنید؛
• سفارش Verify یا Settle نامشخص را ارسال نکنید؛
• تغییر وضعیت به Cancelled یا Refunded را یک عملیات مالی واقعی بدانید؛
• شکست Cancel را فوراً در پنل اسنپ‌پی پیگیری کنید؛
• Eligibility محصول یا سبد را تضمین اعتبار مشتری معرفی نکنید؛
• مبلغ ویجت محصول را «تقریبی» توصیف کنید؛
• کمیسیون را فقط مطابق قرارداد وارد کنید؛
• سایر روش‌های پرداخت را هنگام اختلال اسنپ‌پی در دسترس نگه دارید.

آموزش‌های مرتبط

• تنظیمات مشترک درگاه‌های پرداخت ووکامرس
• راه‌اندازی درگاه پرداخت زرین‌پال ووکامرس
• راه‌اندازی درگاه پرداخت زیبال ووکامرس
• راه‌اندازی درگاه پرداخت سامان SEP ووکامرس
• راه‌اندازی درگاه پرداخت به‌پرداخت ملت ووکامرس
• راه‌اندازی فید محصول Searchwise / Snap ووکامرس
• آشنایی با محیط جم پک و مدیریت ماژول‌ها

منابع فنی

• وب‌سایت اسنپ‌پی
• کانال رسمی اسنپ‌پی
• سند دسترسی و راهنمای فنی پذیرنده اسنپ‌پی؛ نسخه ارائه‌شده در فرایند Onboarding هر فروشگاه
• WooCommerce Payment Gateway API
• WooCommerce Order Statuses

[aio_wc_snappay_instalments]