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

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

برای اطلاعات اتصالِ پرداخت عادی، یک شناسه پذیرنده معتبر (Merchant ID) کافی است. عنوان و توضیحات درگاه، محیط آزمایشی، نوع درگاه، پیام‌های نتیجه و چند گزینه تکمیلی نیز از همان صفحه تنظیمات مدیریت می‌شوند.

این قابلیت در نسخه بررسی‌شده رایگان است و برای فعال‌کردن درگاه زرین‌پال به لایسنس Pro نیاز ندارد.

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

• دریافت و ثبت Merchant ID؛
• راه‌اندازی Sandbox بدون پرداخت واقعی؛
• انتقال از محیط آزمایشی به درگاه عملیاتی؛
• تنظیم عنوان و توضیحات Checkout؛
• انتخاب درگاه عادی، زرین‌گیت یا زرین‌لینک؛
• بررسی کارمزد و گزینه کسر آن؛
• تنظیم پیام پرداخت موفق و ناموفق؛
• شناخت Callback، Authority و Ref ID؛
• کنترل تبدیل ریال و تومان؛
• آزمون Checkout کلاسیک و بلوکی؛
• بررسی وضعیت سفارش و جلوگیری از پردازش تکراری؛
• عیب‌یابی خطاهای ارتباط، پذیرنده، مبلغ و بازگشت.

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

دریافت Merchant ID از زرین‌پال

رابط پنل زرین‌پال ممکن است در طول زمان تغییر کند، اما روند کلی به این صورت است:

1. وارد حساب زرین‌پال شوید.
2. احراز هویت و اطلاعات موردنیاز حساب را تکمیل کنید.
3. از بخش درگاه‌های پرداخت، درگاه مربوط به دامنه فروشگاه را ایجاد یا انتخاب کنید.
4. وضعیت فعال‌بودن درگاه و دامنه متصل به آن را بررسی کنید.
5. Merchant ID را کپی کنید.
6. شناسه را در یک ابزار امن مدیریت رمز یا اطلاعات پذیرندگی نگه دارید.

Merchant ID، Authority و Ref ID کاربردهای متفاوتی دارند:

مقدار	کاربرد
Merchant ID	شناسه ثابت پذیرنده برای اتصال فروشگاه به درگاه
Authority	شناسه موقت درخواست پرداخت که پیش از انتقال مشتری ساخته می‌شود
Ref ID	شماره مرجع تراکنش موفق که پس از Verify دریافت می‌شود

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

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

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

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

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

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

تنظیمات پایه

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

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

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

عنوان درگاه

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

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

پرداخت آنلاین با زرین‌پال

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

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

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

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

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

در توضیحات، شماره حساب، Merchant ID، اطلاعات تماس داخلی یا وعده‌ای درباره زمان تسویه درج نکنید.

تنظیمات حساب زرین‌پال

Merchant ID

Merchant ID فیلد الزامی اتصال است. شناسه محیط عملیاتی را دقیقاً از درگاه مربوط به همان دامنه در پنل زرین‌پال وارد کنید.

هنگام ثبت مقدار:

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

اگر حالت آزمایشی روشن باشد و Merchant ID را خالی بگذارید، افزونه از شناسه آزمایشی پیش‌فرض استفاده می‌کند. می‌توانید یک شناسه معتبر با قالب UUID هم وارد کنید؛ UUID همان قالب شناسه ۳۶ کاراکتری است.

Access Token اختیاری

فیلد Access Token برای سرویس بازگشت وجه در تنظیمات قرار داده شده است، اما برای ایجاد، انتقال یا تأیید پرداخت عادی لازم نیست. اگر فقط قصد دریافت پرداخت دارید، آن را خالی بگذارید.

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

Access Token را مانند رمز نگه دارید و هرگز در تصویر، ویدئو، کد صفحه یا تیکت عمومی نمایش ندهید.

محیط آزمایشی Sandbox

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

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

برای آزمون:

1. گزینه «فعال‌سازی حالت آزمایشی» را روشن کنید.
2. یک UUID معتبر در فیلد Merchant ID وارد کنید؛ یا از مقدار پیش‌فرض آزمایشی استفاده کنید.
3. تنظیمات را ذخیره کنید.
4. یک سفارش آزمایشی ایجاد کنید.
5. زرین‌پال را در Checkout انتخاب کنید.
6. انتقال به دامنه Sandbox را بررسی کنید.
7. یک نتیجه موفق و یک نتیجه لغوشده بسازید.
8. وضعیت و یادداشت‌های سفارش را در ووکامرس کنترل کنید.

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

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

انتقال به محیط عملیاتی

پس از موفقیت آزمون Sandbox:

1. درگاه را موقتاً برای مشتریان خاموش کنید.
2. حالت Sandbox را خاموش کنید.
3. Merchant ID واقعی درگاه همان دامنه را ثبت کنید.
4. تنظیمات را ذخیره کنید.
5. کش مدیریتی و Object Cache مرتبط با تنظیمات را پاک کنید.
6. دامنه، HTTPS و دسترسی Callback را بررسی کنید.
7. درگاه را فعال کنید.
8. یک تراکنش واقعی کم‌مبلغ انجام دهید.
9. مبلغ، Ref ID، وضعیت و یادداشت سفارش را با پنل زرین‌پال تطبیق دهید.

UUID آزمایشی را در محیط عملیاتی باقی نگذارید. همچنین Merchant ID واقعی را با روشن‌بودن Sandbox مبنای آزمون نهایی درگاه زنده در نظر نگیرید.

انتخاب نوع درگاه

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

گزینه	کاربرد
درگاه عادی	حالت پیش‌فرض برای پرداخت معمول زرین‌پال
زرین‌گیت	مسیر اختصاصی زرین‌گیت؛ نیازمند فعال‌سازی این خدمت از سوی زرین‌پال
زرین‌لینک	گزینه مربوط به جریان زرین‌لینک در تنظیمات درگاه

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

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

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

کسر کارمزد از پذیرنده یا مشتری

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

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

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

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

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

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

{transaction_id}

پس از تأیید موفق، این مقدار با Ref ID تراکنش جایگزین می‌شود.

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

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

نمایش پیام را روی صفحه تشکر قالب و Checkout واقعی خود بررسی کنید. پیام پس از تأیید پرداخت در نشست موقت ووکامرس (Session) ذخیره می‌شود. پیش از استفاده عمومی، بررسی کنید صفحه تشکر قالب یا صفحه سفارشی شما آن را نمایش می‌دهد.

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

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

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

{fault}

این مقدار با توضیح خطای شناخته‌شده جایگزین می‌شود.

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

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

پیام را کوتاه و قابل اقدام نگه دارید. اطلاعات فنی حساس، پاسخ خام API، IP سرور یا Merchant ID را به مشتری نمایش ندهید.

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

توضیح پس از خرید

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

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

کد لوگوی اعتماد زرین‌پال

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

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

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

ریال و تومان در زرین‌پال

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

• اگر واحد ووکامرس دقیقاً IRR باشد، مبلغ سفارش بدون تغییر مقیاس ارسال می‌شود؛
• برای سایر واحدها، مبلغ در ۱۰ ضرب می‌شود و به‌عنوان ریال ارسال می‌شود.

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

نمونه فروشگاه تومانی:

جمع سفارش در ووکامرس: 250,000 تومان
مبلغ مورد انتظار در درخواست زرین‌پال: 2,500,000 ریال

نمونه فروشگاه ریالی:

جمع سفارش در ووکامرس: 2,500,000 ریال
مبلغ مورد انتظار در درخواست زرین‌پال: 2,500,000 ریال

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

Callback زرین‌پال

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

aio_wc_zarinpal_return

ساختار URL می‌تواند مشابه نمونه زیر باشد:

https://example.com/?wc-api=aio_wc_zarinpal_return

یک مسیر تأیید سازگار نیز با شناسه زیر ثبت شده است:

aio_wc_zarinpal_verify

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

Callback باید:

• بدون ورود مدیر قابل دسترسی باشد؛
• پشت کش صفحه قرار نگیرد؛
• به دامنه دیگری Redirect نشود؛
• توسط WAF یا افزونه امنیتی مسدود نشود؛
• Query String شامل Authority و Status را حفظ کند؛
• با HTTPS معتبر پاسخ دهد؛
• در حالت تعمیر عمومی مسدود نشود.

زرین‌پال هنگام بازگشت دو مقدار اصلی را در Query String قرار می‌دهد:

پارامتر	کاربرد
Authority	شناسه درخواست پرداخت
Status	نتیجه اولیه بازگشت با مقدار OK یا NOK

فقط Status=OK برای مرحله Verify بررسی می‌شود. این مقدار به‌تنهایی پرداخت را قطعی نمی‌کند.

درخواست، انتقال و Verify چگونه انجام می‌شوند؟

۱. ایجاد درخواست

درگاه اطلاعات زیر را برای زرین‌پال ارسال می‌کند:

• Merchant ID؛
• مبلغ سفارش به ریال؛
• URL بازگشت؛
• توضیحی شامل شماره سفارش؛
• ایمیل صورتحساب؛
• موبایل صورتحساب؛
• شناسه سفارش به‌شکل رشته.

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

۲. انتقال مشتری

مشتری با Authority دریافت‌شده به صفحه StartPay زرین‌پال هدایت می‌شود. محیط Sandbox و عملیاتی آدرس انتقال جداگانه دارند و انتخاب آن‌ها با سوییچ Sandbox انجام می‌شود.

۳. بازگشت مشتری

اگر Status برابر NOK باشد، پرداخت لغوشده یا ناموفق تلقی می‌شود و Verify موفق انجام نمی‌گیرد. اگر مقدار OK باشد، درگاه Merchant ID، Authority و مبلغ همان سفارش را برای Verify ارسال می‌کند.

۴. تأیید پرداخت

در پاسخ Verify:

• کد 100 به معنی تأیید موفق برای نخستین بار است؛
• کد 101 به معنی آن است که همان تراکنش قبلاً تأیید شده است؛
• Ref ID شماره مرجع تراکنش موفق است.

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

پس از تأیید نخستین‌بار:

• payment_complete ووکامرس اجرا می‌شود؛
• Ref ID به‌عنوان شناسه تراکنش ثبت می‌شود؛
• یک یادداشت موفقیت در سفارش افزوده می‌شود؛
• Authority و Ref ID در متای سفارش نگهداری می‌شوند؛
• Session موقت سفارش پاک می‌شود؛
• مشتری به صفحه تشکر هدایت می‌شود.

وضعیت سفارش و اطلاعات قابل بررسی

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

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

• روش پرداخت زرین‌پال؛
• وضعیت پرداخت‌شده سفارش؛
• Transaction ID یا Ref ID؛
• یادداشت «تکمیل پرداخت زرین‌پال»؛
• مبلغ کل سفارش؛
• زمان پرداخت؛
• کاهش موجودی محصول؛
• ایمیل و اعلان‌های پس از پرداخت.

Authority و Ref ID نقش یکسانی ندارند. برای پیگیری مالی با زرین‌پال معمولاً Ref ID اهمیت بیشتری دارد، درحالی‌که Authority برای تطبیق درخواست و Callback استفاده می‌شود.

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

زرین‌پال در جم پک برای هر دو نوع Checkout ووکامرس ثبت می‌شود:

• Checkout کلاسیک مبتنی بر شورت‌کد؛
• Checkout بلوکی ووکامرس.

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

پیش از انتشار، این حالت‌ها را جداگانه آزمایش کنید:

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

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

آزمون Sandbox

• Sandbox روشن است؛
• انتقال به دامنه آزمایشی انجام می‌شود؛
• Authority آزمایشی با S شروع می‌شود؛
• پرداخت موفق سفارش را یک بار تکمیل می‌کند؛
• لغو پرداخت سفارش را پرداخت‌شده نمی‌کند؛
• Refresh صفحه بازگشت عملیات تکمیل را دوباره اجرا نمی‌کند؛
• Ref ID یا نتیجه آزمایشی در سفارش قابل پیگیری است؛
• Checkout موبایل و دسکتاپ کار می‌کنند.

آزمون عملیاتی

• Sandbox خاموش است؛
• Merchant ID واقعی همان دامنه ثبت شده است؛
• مبلغ صفحه پرداخت با سفارش یکسان است؛
• یک تراکنش واقعی کم‌مبلغ موفق انجام می‌شود؛
• Ref ID در سفارش و پنل زرین‌پال تطبیق دارد؛
• وضعیت سفارش درست تغییر می‌کند؛
• موجودی فقط یک بار کم می‌شود؛
• ایمیل و پیامک فقط یک بار ارسال می‌شوند؛
• لغو یا بازگشت ناموفق نیز رفتار صحیح دارد؛
• گزارش و یادداشت سفارش اطلاعات لازم را ثبت می‌کنند.

حالت‌های تکمیلی

• سفارش دارای کد تخفیف؛
• سفارش دارای هزینه ارسال؛
• سفارش دارای مالیات؛
• محصول متغیر؛
• سفارش مهمان؛
• بازگشت با Session منقضی‌شده؛
• بازکردن دوباره URL بازگشت؛
• قطع موقت ارتباط API در محیط آزمایشی؛
• تغییر نوع درگاه و ساخت سفارش جدید.

خطاهای رایج زرین‌پال

کد	مفهوم کاربردی	اقدام پیشنهادی
-9	خطای اعتبارسنجی درخواست	Merchant ID، مبلغ، توضیحات و Callback را بررسی کنید
-10	IP یا Merchant ID معتبر نیست	شناسه، دامنه و محدودیت IP حساب را بررسی کنید
-11	درگاه فعال نیست	وضعیت درگاه را در پنل زرین‌پال و پشتیبانی بررسی کنید
-12	تلاش بیش از حد در بازه کوتاه	درخواست‌های تکراری را متوقف و بعداً دوباره آزمایش کنید
-14	دامنه Callback با دامنه درگاه هماهنگ نیست	دامنه پنل زرین‌پال و URL اصلی سایت را تطبیق دهید
-15	درگاه تعلیق شده است	وضعیت حساب را از پشتیبانی زرین‌پال پیگیری کنید
-16	سطح تأیید پذیرنده کافی نیست	مراحل احراز و ارتقای سطح حساب را تکمیل کنید
-50	مبلغ Verify با مبلغ درخواست یکسان نیست	واحد پول، جمع سفارش و تغییرات پس از انتقال را بررسی کنید
-51	پرداخت ناموفق است	سفارش را پرداخت‌شده نکنید و امکان تلاش دوباره بدهید
-52	خطای غیرمنتظره سرویس	زمان رخداد و شناسه‌ها را برای پشتیبانی آماده کنید
-53	تراکنش متعلق به این Merchant ID نیست	شناسه محیط یا درگاه را بررسی کنید
-54	Authority نامعتبر است	URL بازگشت و Authority ذخیره‌شده را بررسی کنید
-101	تراکنش پیدا نشد	محیط Sandbox یا عملیاتی و شناسه درخواست را تطبیق دهید
100	پرداخت با موفقیت تأیید شد	Ref ID و وضعیت سفارش را کنترل کنید
101	تراکنش قبلاً تأیید شده است	از پردازش دوباره سفارش جلوگیری و نتیجه قبلی را نمایش دهید

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

عیب‌یابی

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

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

• فعال‌سازی درگاه را بررسی کنید؛
• Merchant ID را کامل کنید؛
• تنظیمات را ذخیره و صفحه Checkout را بدون کش باز کنید؛
• واحد پول و مبلغ سفارش را بررسی کنید؛
• درگاه را در «ووکامرس ← پیکربندی ← پرداخت‌ها» کنترل کنید؛
• تداخل قالب، افزونه Checkout یا خطای JavaScript را در محیط آزمایشی بررسی کنید؛
• اگر Checkout بلوکی است، فایل‌های بهینه‌شده JavaScript را بازسازی کنید.

هشدار خالی‌بودن Merchant ID دیده می‌شود

درگاه فعال شده اما شناسه اصلی پذیرنده ثبت نشده است. Merchant ID را از پنل زرین‌پال کپی و در بخش حساب وارد کنید. اگر در Sandbox هستید نیز بهتر است یک UUID معتبر داشته باشید.

خطای -10 یا -11 دریافت می‌شود

• Merchant ID را دوباره از پنل کپی کنید؛
• مطمئن شوید Sandbox و اطلاعات عملیاتی با هم ترکیب نشده‌اند؛
• وضعیت فعال‌بودن درگاه را بررسی کنید؛
• دامنه و IP ثبت‌شده در حساب را کنترل کنید؛
• اگر سرور یا IP تغییر کرده است، موضوع را با زرین‌پال بررسی کنید.

خطای -14 مربوط به Callback نمایش داده می‌شود

• دامنه ثبت‌شده برای درگاه را با home_url وردپرس مقایسه کنید؛
• تفاوت www و بدون www را بررسی کنید؛
• HTTP و HTTPS را یکسان کنید؛
• دامنه آزمایشی، Staging یا Alias را از دامنه عملیاتی جدا کنید؛
• Redirectهای CDN و وب‌سرور را کنترل کنید.

مشتری به زرین‌پال منتقل نمی‌شود

• خطای نمایش‌داده‌شده در Checkout را ثبت کنید؛
• دسترسی خروجی HTTPS سرور را بررسی کنید؛
• DNS، TLS، cURL و فایروال هاست را کنترل کنید؛
• Merchant ID و نوع درگاه را بررسی کنید؛
• اگر زرین‌گیت انتخاب شده، فعال‌بودن آن را از زرین‌پال تأیید کنید؛
• یک سفارش ساده با مبلغ کوچک و بدون تخفیف بسازید.

صفحه پرداخت مبلغ اشتباه نشان می‌دهد

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

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

• Ref ID و تراکنش را در پنل زرین‌پال بررسی کنید؛
• یادداشت‌های سفارش را بخوانید؛
• مسیر Callback را از کش، WAF و ورود اجباری مستثنا کنید؛
• امکان اتصال سرور به API Verify زرین‌پال را بررسی کنید؛
• خطاهای -50 تا -54 را کنترل کنید؛
• مبلغ و Merchant ID مرحله درخواست و Verify باید یکسان باشند؛
• پیش از تغییر دستی وضعیت، نتیجه تراکنش را با زرین‌پال تطبیق دهید.

مشتری پرداخت را لغو کرده است

بازگشت با Status=NOK به معنی پرداخت ناموفق یا لغوشده است. سفارش نباید پرداخت‌شده شود. مشتری می‌تواند از صفحه پرداخت سفارش دوباره تلاش کند یا روش دیگری را انتخاب کند.

اگر وجهی کسر شده اما نتیجه NOK است، با Ref ID یا اطلاعات پنل زرین‌پال وضعیت واقعی را پیگیری کنید و صرفاً بر اساس پیام مرورگر تصمیم نگیرید.

با Refresh چند یادداشت یا اعلان ایجاد می‌شود

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

• نسخه جم پک را بررسی کنید؛
• افزونه دیگری را که روی Callback یا payment_complete عمل می‌کند شناسایی کنید؛
• یادداشت‌ها و زمان هر اجرا را مقایسه کنید؛
• لاگ پاک‌سازی‌شده و شناسه سفارش را برای پشتیبانی آماده کنید.

Sandbox کار می‌کند اما درگاه عملیاتی خطا دارد

• Sandbox را خاموش کنید؛
• UUID آزمایشی را با Merchant ID واقعی جایگزین کنید؛
• فعال‌بودن درگاه و دامنه را در پنل زرین‌پال بررسی کنید؛
• محدودیت IP و وضعیت احراز حساب را کنترل کنید؛
• کش تنظیمات را پاک کنید؛
• یک سفارش تازه و کم‌مبلغ بسازید.

ارتباط با API Timeout یا SSL Error دارد

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

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

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

منابع فنی

• مستندات رسمی درگاه پرداخت زرین‌پال
• راهنمای رسمی اتصال، بازگشت و Verify زرین‌پال
• راهنمای رسمی Sandbox زرین‌پال
• فهرست رسمی خطاهای زرین‌پال
• راهنمای رسمی واحد پول زرین‌پال
• مستندات رسمی استرداد وجه زرین‌پال
• WooCommerce Payment Gateway API