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

درگاه سامان SEP جم پک، فروشگاه ووکامرسی را به درگاه پرداخت اینترنتی شرکت پرداخت الکترونیک سامان کیش متصل می‌کند. ابتدا برای سفارش، یک شناسه موقت پرداخت یا «توکن» دریافت می‌شود. سپس مشتری از صفحه‌ای در فروشگاه به درگاه می‌رود. پس از بازگشت به فروشگاه (Callback)، جم پک تراکنش را با سرویس تأیید سامان (Verify) بررسی می‌کند و در صورت تأیید معتبر، سفارش تکمیل می‌شود.

این درگاه چند الزام مهم دارد:

• مبلغ همیشه به ریال ارسال می‌شود؛
• IP خروجی سرور باید برای ترمینال نزد سامان ثبت شده باشد؛
• مشتری باید از صفحه فروشگاه وارد درگاه شود تا مرورگر، نشانی مبدأ یا Referer را ارسال کند؛
• تراکنش باید در بازه تعیین‌شده سامان، معمولاً حداکثر ۳۰ دقیقه، Verify شود؛
• مبلغ تأییدشده باید دقیقاً با مبلغ ذخیره‌شده سفارش برابر باشد؛
• RefNum نباید برای بیش از یک سفارش پذیرفته شود.

این قابلیت Pro است و برای آغاز پرداخت جدید به لایسنس معتبر جم پک نیاز دارد.

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

• دریافت درگاه و Terminal ID سامان؛
• ثبت IP خروجی صحیح سرور؛
• تنظیم عنوان و توضیحات Checkout؛
• ارسال اختیاری شماره موبایل مشتری؛
• تنظیم مدت اعتبار توکن؛
• دریافت توکن و انتقال فرم‌محور به SEP؛
• شناخت ResNum، RefNum، TraceNo و RRN؛
• Callback و تطبیق آن با سفارش؛
• Verify تراکنش و کنترل مبلغ؛
• Reverse در صورت مغایرت مبلغ؛
• مدیریت تراکنش نامشخص یا قبلاً تأییدشده؛
• فعال‌سازی موقت Debug Log؛
• عیب‌یابی IP، Referer، توکن، Callback و Verify.

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

دریافت درگاه و Terminal ID

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

1. درخواست درگاه اینترنتی حقیقی یا حقوقی را ثبت کنید.
2. احراز هویت، اطلاعات مالیاتی، نماد اعتماد و مدارک کسب‌وکار را تکمیل کنید.
3. دامنه فروشگاه و رویه فروش را برای بررسی ارائه دهید.
4. قرارداد و تعهدنامه‌های لازم را تکمیل کنید.
5. Terminal ID را دریافت کنید.
6. IP خروجی سرور را برای ترمینال اعلام کنید.
7. در صورت ارائه دسترسی محدود آزمایشی، تراکنش تعیین‌شده را اجرا کنید.
8. پس از تأیید فنی، وضعیت عملیاتی ترمینال را بررسی کنید.

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

Terminal ID را با شماره پذیرنده، شماره حساب، شناسه قرارداد یا شناسه تراکنش اشتباه نگیرید.

IP خروجی سرور چیست؟

IP موردنیاز سامان لزوماً همان IP دامنه یا IP کامپیوتر مدیر سایت نیست. باید IPای را ثبت کنید که درخواست‌های خروجی PHP و وردپرس از طریق آن به sep.shaparak.ir می‌رسند.

این IP ممکن است با IP دامنه، CDN، مدیریت هاست یا بازدیدکننده فرق داشته باشد. برای ثبت مقدار درست، آن را از شرکت هاست بگیرید.

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

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

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

برای دسترسی به تنظیمات:

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

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

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

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

تنظیمات پایه

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

این گزینه، نمایش سامان SEP در تسویه‌حساب را کنترل می‌کند. ابتدا Terminal ID و IP خروجی را آماده کنید و درگاه را در محیط کنترل‌شده آزمایش کنید. پس از بررسی نتیجه، آن را برای مشتریان فعال کنید.

اگر Terminal ID خالی باشد، جم پک هشدار مدیریتی نمایش می‌دهد و درگاه آماده دریافت پرداخت نخواهد بود.

عنوان درگاه

عنوان در Checkout به مشتری نمایش داده می‌شود. مقدار پیش‌فرض نسخه بررسی‌شده «بانک سامان» است.

نمونه پیشنهادی:

پرداخت آنلاین با سامان SEP

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

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

توضیحات زیر عنوان روش پرداخت نمایش داده می‌شود. نمونه پیشنهادی:

پرداخت امن سفارش با کارت‌های عضو شبکه شتاب از طریق درگاه سامان SEP

اطلاعات ترمینال، IP سرور یا جزئیات قرارداد را در این متن قرار ندهید.

ثبت Terminal ID

1. Terminal ID را از پیام یا پنل رسمی SEP دریافت کنید.
2. مقدار را بدون فاصله اضافه در فیلد «Terminal ID» وارد کنید.
3. تنظیمات را ذخیره کنید.
4. صفحه را دوباره باز و مقدار ذخیره‌شده را بررسی کنید.
5. یک درخواست توکن کنترل‌شده انجام دهید.

Terminal ID در درخواست توکن به‌شکل رشته و هنگام Verify و Reverse به‌شکل عدد ارسال می‌شود. بنابراین فقط مقدار عددی اعلام‌شده از سوی SEP را وارد کنید و صفر یا نویسه اضافی به آن نیفزایید.

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

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

شماره‌های زیر به قالب ده‌رقمی شروع‌شونده با 9 تبدیل می‌شوند:

09121234567
989121234567
00989121234567

خروجی نمونه:

9121234567

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

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

مدت اعتبار توکن

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

فقط عدد صحیح مثبت وارد کنید. SEP می‌تواند مقدارهای خارج از بازه مجاز خود را محدود یا رد کند؛ بنابراین بازه قراردادی یا مستند فنی جاری ترمینال را ملاک قرار دهید.

مدت بسیار کوتاه ممکن است باعث انقضای توکن پیش از تکمیل پرداخت شود. مدت بسیار طولانی نیز بدون نیاز عملی توصیه نمی‌شود.

پیام پرداخت موفق

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

{transaction_id}

این مقدار با RefNum تأییدشده سامان جایگزین می‌شود.

نمونه پیشنهادی:

پرداخت سفارش با موفقیت تأیید شد. شماره رسید سامان: {transaction_id}

پیام پرداخت ناموفق

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

{fault}

نمونه پیشنهادی:

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

پیام مشتری باید ساده باشد. جزئیات فنی ارتباط، Terminal ID، IP یا پاسخ خام سرویس را فقط در سفارش و گزارش مدیریتی نگه دارید.

گزارش فنی Debug

گزینه «ثبت درخواست‌های درگاه» برای عیب‌یابی موقت است. منبع گزارش:

aio-wc-saman

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

1. به «ووکامرس ← وضعیت ← گزارش‌ها» بروید.
2. منبع aio-wc-saman را انتخاب کنید.
3. زمان سفارش یا RefNum را در گزارش پیدا کنید.

وقتی Debug خاموش است، خطاهای مهم همچنان ثبت می‌شوند. با روشن‌کردن آن، درخواست‌ها و پاسخ‌های بیشتری برای دریافت توکن، Callback، Verify و Reverse نوشته می‌شوند.

Debug را فقط هنگام بررسی مشکل روشن کنید و پس از پایان خاموش کنید. گزارش خام می‌تواند حاوی Terminal ID، URL بازگشت، ResNum، RefNum و جزئیات پاسخ سرویس باشد. پیش از اشتراک گزارش، تمام اطلاعات غیرضروری را حذف کنید.

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

چرا انتقال با فرم انجام می‌شود؟

سامان نشانی مبدأ مرورگر (Referer) را بررسی می‌کند. برای ارسال این نشانی، جم پک پس از دریافت توکن ابتدا صفحه رسید فروشگاه را باز می‌کند و از آنجا فرم پرداخت را به SEP می‌فرستد.

روند انتقال:

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

این توقف کوتاه روی صفحه فروشگاه بخشی از جریان صحیح است و نباید با Redirect سفارشی حذف شود.

کنترل Referrer-Policy

اگر سایت هدر زیر را ارسال کند، مرورگر Referer را حذف می‌کند و سامان ممکن است ورود را رد کند:

Referrer-Policy: no-referrer

مقدار same-origin نیز برای درخواست میان دو دامنه می‌تواند Referer را حذف کند. سیاستی انتخاب کنید که حداقل Origin سایت را در انتقال HTTPS به HTTPS حفظ کند و نتیجه را روی مرورگرهای واقعی آزمایش کنید.

افزونه امنیتی، CDN، تنظیمات سرور یا کد قالب می‌توانند این هدر را تغییر دهند. صفحه رسید و درخواست POST به sep.shaparak.ir را در ابزار Network مرورگر بررسی کنید.

ریال و تومان

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

واحد سفارش	رفتار تبدیل به ریال
IRR	بدون تغییر
IRT و نام‌های رایج تومان	ضرب در ۱۰
IRHT، هزار تومان	ضرب در ۱۰٬۰۰۰
IRHR، هزار ریال	ضرب در ۱٬۰۰۰

برای نمونه:

جمع سفارش: 420,000 تومان
مبلغ مورد انتظار سامان: 4,200,000 ریال

مبلغ ریالی هنگام دریافت توکن در متای سفارش ذخیره می‌شود. پس از Verify، مقدار OrginalAmount پاسخ سامان با همین مبلغ مقایسه خواهد شد؛ املای OrginalAmount مطابق نام فیلد سرویس است.

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

شناسه‌های پرداخت سامان

شناسه	سازنده	کاربرد
ResNum	فروشگاه	شناسه یکتای هر تلاش پرداخت و اتصال Callback به سفارش
Token	سامان	ورود مشتری به صفحه پرداخت
RefNum	سامان	رسید تراکنش و Transaction ID اصلی سفارش
TraceNo	سامان	شماره پیگیری یا Trace تراکنش
RRN	شبکه پرداخت	شماره مرجع بازیابی تراکنش
MaskedPan یا SecurePan	سامان	شماره کارت ماسک‌شده

جم پک برای هر تلاش، ResNum را با ترکیب شناسه سفارش و زمان می‌سازد:

ORDER_ID-TIMESTAMP

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

Token محرمانه و کوتاه‌عمر است و نباید در تصویر، گزارش عمومی یا ابزار آمار ثبت شود.

دریافت توکن

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

https://sep.shaparak.ir/OnlinePG/OnlinePG

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

• action=token؛
• Terminal ID؛
• مبلغ ریالی سفارش؛
• ResNum یکتای تلاش پرداخت؛
• URL بازگشت؛
• شماره موبایل نرمال‌شده، در صورت فعال‌بودن؛
• مدت اعتبار توکن، در صورت ثبت.

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

انتقال مشتری به سامان

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

POST https://sep.shaparak.ir/OnlinePG/OnlinePG
Token=PAYMENT_TOKEN

وجود فرم روی دامنه فروشگاه برای Referer لازم است. صفحه پرداخت سفارش را از کش، بهینه‌سازی HTML مخرب، حذف Script و Redirect سفارشی مستثنا کنید.

اگر انتقال خودکار انجام نشود، مشتری می‌تواند دکمه «پرداخت با سامان» را انتخاب کند.

Callback سامان

شناسه Callback نسخه بررسی‌شده:

aio_wc_saman

URL بازگشت با WC-API ووکامرس ساخته و شناسه سفارش با wc_order به آن افزوده می‌شود:

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

بسته به پیوندهای یکتا، ساختار Query String نیز ممکن است استفاده شود:

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

سامان معمولاً نتیجه را با POST برمی‌گرداند؛ کد نسخه بررسی‌شده GET را نیز به‌عنوان حالت جایگزین می‌پذیرد.

پارامترهای اصلی بازگشت:

پارامتر	کاربرد
State	نتیجه متنی؛ فقط OK برای ادامه پذیرفته می‌شود
Status	کد وضعیت پرداخت
RefNum	رسید تراکنش برای Verify
ResNum	شناسه تلاش پرداخت ساخته‌شده در فروشگاه

Callback باید عمومی، HTTPS، بدون کش و بدون ورود اجباری باشد. WAF نباید POST سامان یا پارامترهای آن را حذف کند.

تطبیق Callback با سفارش

جم پک برای پذیرش Callback فقط به wc_order اعتماد نمی‌کند. ResNum بازگشتی باید با مقدار ذخیره‌شده همان سفارش برابر باشد.

اگر wc_order حذف یا نامعتبر باشد، درگاه:

1. شناسه احتمالی سفارش را از ابتدای ResNum استخراج می‌کند؛
2. مقدار کامل ResNum را با متای سفارش تطبیق می‌دهد؛
3. در صورت نیاز، سفارش را از روی متای ذخیره‌شده جست‌وجو می‌کند.

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

کنترل استفاده تکراری از RefNum

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

این کنترل ضروری است، زیرا سرویس سامان ممکن است یک RefNum را بیش از یک بار Verify کند. یک رسید نباید برای پرداخت دو سفارش مصرف شود.

Verify تراکنش

پس از State=OK و وجود RefNum، درخواست تأیید به مسیر زیر ارسال می‌شود:

https://sep.shaparak.ir/verifyTxnRandomSessionkey/ipg/VerifyTransaction

بدنه درخواست شامل RefNum و TerminalNumber است.

نتیجه‌های پذیرفته‌شده:

• ResultCode=0: تأیید موفق؛
• ResultCode=2: درخواست تأیید قبلاً انجام شده است.

برای نتیجه موفق اولیه، مبلغ OrginalAmount از TransactionDetail خوانده و با مبلغ ریالی ذخیره‌شده سفارش مقایسه می‌شود.

محدودیت ۳۰ دقیقه

تراکنش باید در بازه اعلام‌شده سامان Verify شود. اگر بیش از حدود ۳۰ دقیقه از تراکنش بگذرد، ممکن است کد -6 دریافت شود و مبلغ به‌صورت خودکار بازگردد.

در فاصله پرداخت تا Verify:

• Callback نباید مسدود شود؛
• ارتباط خروجی سرور باید برقرار باشد؛
• سایت نباید در حالت تعمیر یا خاموش باشد؛
• کش یا CDN نباید پاسخ Callback را نگه دارد؛
• تغییر DNS یا SSL نباید مسیر بازگشت را قطع کند.

وقتی Verify پاسخ قطعی نمی‌دهد

اگر مشتری پرداخت کرده اما سرویس Verify در دسترس نباشد، جم پک سفارش را «در انتظار بررسی» قرار می‌دهد و آن را تکمیل نمی‌کند. یادداشت سفارش تأکید می‌کند که پیش از ارسال کالا باید پنل سامان بررسی شود.

در این وضعیت:

1. RefNum و مبلغ را در پنل SEP جست‌وجو کنید.
2. نتیجه Verify و وضعیت بازگشت خودکار را بررسی کنید.
3. کالا یا خدمت را تا مشخص‌شدن نتیجه تحویل ندهید.
4. سفارش را فقط پس از تطبیق مستند تراکنش به وضعیت مناسب ببرید.

اگر پاسخ با کد 2 برگردد اما مبلغ نداشته باشد، سفارش «در انتظار بررسی» می‌ماند. در این حالت، پرداخت تکمیل یا برگشت داده نمی‌شود؛ مدیر باید مبلغ را در پنل بررسی کند.

مغایرت مبلغ و Reverse

اگر مبلغ تأییدشده با مبلغ ذخیره‌شده سفارش برابر نباشد، جم پک درخواست Reverse را به مسیر زیر می‌فرستد:

https://sep.shaparak.ir/verifyTxnRandomSessionkey/ipg/ReverseTransaction

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

پس از مغایرت:

• سفارش تکمیل نمی‌شود؛
• RefNum در سفارش ذخیره می‌شود؛
• اختلاف مبلغ در یادداشت ثبت می‌شود؛
• درخواست Reverse ارسال می‌شود؛
• نتیجه عملیات در گزارش aio-wc-saman ثبت می‌شود.

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

تکمیل سفارش موفق

وقتی Verify موفق و مبلغ منطبق باشد:

• RefNum به‌عنوان Transaction ID ووکامرس ذخیره می‌شود؛
• TraceNo در متای پیگیری ذخیره می‌شود؛
• RRN در متای اختصاصی سامان ذخیره می‌شود؛
• شماره کارت با بخشی از ارقام پوشانده‌شده، در صورت وجود، نگهداری می‌شود؛
• payment_complete ووکامرس اجرا می‌شود؛
• یادداشت جزئیات تراکنش به سفارش افزوده می‌شود؛
• سبد خرید فعال خالی می‌شود؛
• پیام موفق با RefNum نمایش داده می‌شود.

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

وضعیت سفارش پس از پرداخت

پس از payment_complete، وضعیت نهایی را ووکامرس بر اساس نوع محصولات تعیین می‌کند:

• سفارش کالای فیزیکی معمولاً «در حال انجام» می‌شود؛
• سفارش فقط شامل محصول مجازی یا دانلودی ممکن است «تکمیل‌شده» شود؛
• Verify نامشخص یا بدون مبلغ قابل کنترل روی «در انتظار بررسی» قرار می‌گیرد؛
• پرداخت لغوشده، نامعتبر یا دارای خطای قطعی «ناموفق» می‌شود.

در صفحه سفارش این موارد را بررسی کنید:

• روش پرداخت سامان SEP؛
• وضعیت سفارش؛
• Transaction ID برابر RefNum؛
• TraceNo و RRN در یادداشت یا متای سفارش؛
• شماره کارت فقط به‌شکل ماسک‌شده؛
• مبلغ و زمان پرداخت؛
• کاهش موجودی فقط یک بار؛
• ایمیل، پیامک و عملیات جانبی فقط یک بار.

Checkout کلاسیک و بلوکی

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

این سناریوها را جداگانه آزمایش کنید:

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

چک‌لیست پیش از آزمون

• لایسنس Pro معتبر است؛
• Terminal ID درست ثبت شده است؛
• IP خروجی فعلی سرور نزد SEP ثبت شده است؛
• دامنه و HTTPS صحیح‌اند؛
• پورت خروجی ۴۴۳ باز است؛
• Referrer-Policy انتقال بین دامنه‌ای را مسدود نمی‌کند؛
• صفحه رسید و Callback کش نمی‌شوند؛
• WAF درخواست POST سامان را می‌پذیرد؛
• واحد پول و تبدیل ریال بررسی شده‌اند؛
• Debug فقط در صورت نیاز روشن است؛
• سفارش و اطلاعات مشتری آزمایشی آماده‌اند.

سناریوهای ضروری آزمون

سناریو	نتیجه مورد انتظار
دریافت توکن موفق	Token ذخیره و مشتری به صفحه رسید هدایت شود
انتقال فرم‌محور	فرم با Referer مناسب به SEP ارسال شود
پرداخت موفق	Verify، تطبیق مبلغ و تکمیل یک‌باره سفارش انجام شود
لغو توسط مشتری	سفارش ناموفق بماند و امکان تلاش دوباره وجود داشته باشد
Terminal ID نادرست	خطای قابل پیگیری ثبت و انتقال متوقف شود
IP ثبت‌نشده	Timeout یا خطای IP با راهنمای مناسب ثبت شود
Token منقضی	سفارش پرداخت‌شده نشود و تلاش تازه ممکن باشد
Callback بدون Session	سفارش از ResNum صحیح پیدا شود
Callback تکراری	تکمیل سفارش و اعلان‌ها دوباره اجرا نشوند
RefNum تکراری برای سفارش دیگر	رسید رد و سفارش دوم تکمیل نشود
Verify قطع‌شده	سفارش «در انتظار بررسی» قرار بگیرد
Verify قبلی بدون مبلغ	سفارش برای بررسی دستی نگه داشته شود
مغایرت مبلغ	سفارش تکمیل نشود و Reverse درخواست شود
JavaScript خاموش	دکمه انتقال دستی قابل استفاده باشد
Checkout موبایل	انتقال و بازگشت بدون گم‌شدن سفارش انجام شود

کدهای وضعیت بازگشت

کد یا State	مفهوم کاربردی
1 یا CanceledByUser	مشتری پرداخت را لغو کرده است
2	پرداخت در سمت درگاه موفق گزارش شده است
3 یا Failed	پرداخت انجام نشده است
4 یا SessionIsNull	در زمان مجاز پاسخی دریافت نشده است
5 یا InvalidParameters	پارامترهای ارسال‌شده معتبر نیستند
8 یا MerchantIpAddressIsInvalid	IP سرور برای ترمینال مجاز نیست
10 یا TokenNotFound	Token پیدا نشده است
11 یا TokenRequired	ترمینال فقط پرداخت توکن‌محور را می‌پذیرد
12 یا TerminalNotFound	شماره ترمینال پیدا نشده است
21 یا MultisettlePolicyErrors	قواعد تسهیم ترمینال رعایت نشده‌اند

تنها State=OK اجازه ورود به مرحله Verify را می‌دهد. کد وضعیت مثبت به‌تنهایی برای تکمیل سفارش کافی نیست.

کدهای Verify و Reverse

کد	مفهوم	اقدام
0	عملیات موفق	مبلغ و جزئیات تراکنش بررسی شوند
2	تأیید قبلاً درخواست شده است	وضعیت سفارش و وجود مبلغ بررسی شود
5	تراکنش Reverse شده است	سفارش تحویل داده نشود
-2	تراکنش پیدا نشد	RefNum، ترمینال و محیط بررسی شوند
-6	بیش از نیم ساعت گذشته است	پنل سامان و وضعیت بازگشت وجه بررسی شوند
-104	ترمینال غیرفعال است	وضعیت قرارداد از SEP پیگیری شود
-105	ترمینال وجود ندارد	Terminal ID اصلاح شود
-106	IP درخواست‌کننده مجاز نیست	IP خروجی واقعی ثبت شود

کدها و شرح سرویس ممکن است تغییر کنند. پاسخ و مستند فنی جاری ترمینال را مرجع نهایی قرار دهید.

عیب‌یابی

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

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

• سوییچ درگاه را بررسی کنید؛
• لایسنس Pro را کنترل کنید؛
• Terminal ID را کامل کنید؛
• روش پرداخت را در پیکربندی ووکامرس بررسی کنید؛
• Checkout را بدون کش باز کنید؛
• واحد پول و مبلغ سفارش را کنترل کنید؛
• خطای JavaScript یا تداخل افزونه Checkout را بررسی کنید.

دریافت Token با Timeout متوقف می‌شود

رایج‌ترین علت، ثبت‌نبودن IP خروجی یا تغییر آن پس از مهاجرت است. سامان ممکن است اتصال IP غیرمجاز را بدون پاسخ رها کند و نتیجه به‌صورت Timeout دیده شود.

• IP خروجی واقعی PHP را از هاست بگیرید؛
• آن را با IP ثبت‌شده ترمینال تطبیق دهید؛
• DNS دامنه sep.shaparak.ir را بررسی کنید؛
• پورت خروجی ۴۴۳ و فایروال را کنترل کنید؛
• گزارش aio-wc-saman و یادداشت سفارش را بخوانید؛
• تغییر اخیر سرور، Proxy یا NAT را بررسی کنید.

خطای DNS، SSL یا Certificate دیده می‌شود

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

Token دریافت می‌شود اما مشتری وارد درگاه نمی‌شود

• صفحه رسید سفارش را از کش خارج کنید؛
• وجود فرم aio-wc-saman-form را بررسی کنید؛
• خطاهای JavaScript را کنترل کنید؛
• دکمه دستی پرداخت را آزمایش کنید؛
• Token ذخیره‌شده سفارش و زمان اعتبار آن را بررسی کنید؛
• بهینه‌ساز HTML یا Script را برای صفحه رسید غیرفعال کنید.

سامان خطای Referer می‌دهد

• انتقال را مستقیماً با Redirect سفارشی جایگزین نکنید؛
• Referrer-Policy را بررسی کنید؛
• مقدارهای no-referrer و same-origin را برای این مسیر بازبینی کنید؛
• افزونه امنیتی و CDN را کنترل کنید؛
• درخواست فرم به SEP را در Network مرورگر ببینید؛
• انتقال را در مرورگر و موبایل واقعی آزمایش کنید.

Terminal ID پیدا نمی‌شود یا غیرفعال است

• مقدار را بدون فاصله و نویسه اضافی وارد کنید؛
• شماره پذیرنده را به‌جای Terminal ID ثبت نکنید؛
• وضعیت فعال ترمینال را از SEP بپرسید؛
• دامنه و IP مربوط به همان ترمینال را بررسی کنید؛
• پس از اصلاح، سفارش جدید بسازید.

مشتری پرداخت کرده اما سفارش «در انتظار بررسی» است

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

• کالا را ارسال نکنید؛
• RefNum را در پنل SEP جست‌وجو کنید؛
• مبلغ، وضعیت Verify و Reverse را بررسی کنید؛
• یادداشت سفارش و گزارش خطا را بخوانید؛
• نتیجه را با واحد مالی یا پشتیبانی SEP تطبیق دهید؛
• فقط پس از تأیید مستند، وضعیت سفارش را اصلاح کنید.

خطای مغایرت مبلغ ثبت شده است

• واحد پول سفارش را بررسی کنید؛
• جمع نهایی شامل ارسال، مالیات و تخفیف را محاسبه کنید؛
• مبلغ ذخیره‌شده هنگام Token را با OrginalAmount مقایسه کنید؛
• افزونه چندارزی یا تغییر قیمت را بررسی کنید؛
• نتیجه Reverse را در گزارش و پنل SEP کنترل کنید؛
• سفارش را تحویل ندهید.

Reverse درخواست شده اما نتیجه مشخص نیست

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

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

• گزارش aio-wc-saman را بررسی کنید؛
• RefNum و رسید برگشت را در پنل SEP جست‌وجو کنید؛
• وضعیت مغایرت را مطابق فرایند SEP پیگیری کنید؛
• تا تعیین تکلیف، سفارش را پرداخت‌شده یا تکمیل‌شده نکنید.

Callback به سفارش متصل نمی‌شود

• وجود ResNum و wc_order را بررسی کنید؛
• Redirectهای دامنه نباید Query String را حذف کنند؛
• WAF نباید POST Callback را مسدود کند؛
• سفارش و متای ResNum را بررسی کنید؛
• گزارش خطای Callback بدون سفارش را پیدا کنید؛
• تراکنش را با RefNum در پنل سامان بررسی کنید.

خطای استفاده تکراری از رسید دیده می‌شود

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

کد -6 دریافت می‌شود

بیش از زمان مجاز Verify گذشته است. پنل SEP را برای وضعیت بازگشت خودکار بررسی کنید. سفارش را بدون تأیید مالی تحویل ندهید.

Debug روشن است اما گزارش مناسب پیدا نمی‌شود

• منبع aio-wc-saman و تاریخ درست را انتخاب کنید؛
• ساعت سرور و زمان سفارش را مقایسه کنید؛
• مطمئن شوید WooCommerce Logger قابل نوشتن است؛
• شکست‌های قطعی حتی با Debug خاموش باید ثبت شوند؛
• شناسه سفارش یا RefNum را جست‌وجو کنید.

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

• Terminal ID و گزارش کامل را عمومی نکنید؛
• Token را مانند داده محرمانه کوتاه‌عمر نگه دارید؛
• RefNum را فقط به سفارش منطبق با ResNum اختصاص دهید؛
• شماره کارت فقط به‌شکل ماسک‌شده ذخیره یا نمایش داده شود؛
• Callback نباید به ورود کاربر یا Session وابسته باشد؛
• Verify موفق و تطبیق مبلغ پیش‌نیاز تحویل سفارش است؛
• نتیجه Reverse را از پنل SEP تأیید کنید؛
• Debug را پس از عیب‌یابی خاموش کنید؛
• گزارش را پیش از ارسال برای پشتیبانی پاک‌سازی کنید؛
• پس از تغییر هاست، IP خروجی و پرداخت واقعی را دوباره آزمایش کنید.

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

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

منابع فنی

• صفحه رسمی درگاه پرداخت اینترنتی SEP
• راهنما و مستندات فنی رسمی SEP
• شرایط و مدارک رسمی درگاه اینترنتی SEP
• WooCommerce Payment Gateway API
• WooCommerce Plugin API callbacks