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

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

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

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

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

• دریافت و ثبت Merchant ID زیبال؛
• تنظیم عنوان و توضیحات روش پرداخت؛
• فعال‌سازی و آزمون Sandbox؛
• انتقال امن به محیط عملیاتی؛
• شناخت trackId، refNumber و orderId؛
• نحوه ساخت Callback و بازیابی سفارش؛
• تبدیل مبلغ ریال، تومان، هزار تومان و هزار ریال؛
• بررسی مبلغ بازگشتی از Verify؛
• مدیریت پرداخت موفق، لغوشده و قبلاً تأییدشده؛
• آزمون Checkout کلاسیک و بلوکی؛
• رفع خطاهای Merchant، مبلغ، Callback و ارتباط API.

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

دریافت Merchant ID از زیبال

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

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

Merchant ID شناسه ثابت پذیرنده است و نباید با شناسه‌های هر تراکنش اشتباه گرفته شود:

مقدار	زمان ایجاد	کاربرد
Merchant ID	هنگام ایجاد درگاه پذیرنده	شناسایی درگاه فروشگاه نزد زیبال
trackId	پس از درخواست موفق پرداخت	انتقال مشتری و Verify تراکنش
refNumber	در پاسخ تراکنش موفق زیبال	شماره مرجع مالی ارائه‌شده از سوی زیبال
orderId	هنگام ساخت سفارش در فروشگاه	ارتباط درخواست زیبال با سفارش ووکامرس

در نسخه بررسی‌شده، trackId به‌عنوان Transaction ID ووکامرس ذخیره و در پیام موفق استفاده می‌شود. refNumber احتمالی پاسخ Verify در سفارش ذخیره نمی‌شود؛ برای مشاهده آن باید تراکنش متناظر را در پنل زیبال بررسی کنید.

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

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

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

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

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

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

تنظیمات پایه

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

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

اگر Merchant ID وارد نشده باشد، فعال‌کردن درگاه باعث آماده‌شدن یک اتصال عملیاتی معتبر نمی‌شود. ابتدا Sandbox را آزمایش یا اطلاعات واقعی را کامل کنید.

عنوان درگاه

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

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

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

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

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

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

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

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

این متن محل نمایش اطلاعات پذیرندگی، شماره حساب، شرایط تسویه یا توضیحات طولانی نیست.

ثبت Merchant ID

برای محیط عملیاتی:

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

هنگام ثبت شناسه:

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

حالت آزمایشی Sandbox

زیبال برای آزمون درگاه از مقدار ثابت زیر به‌عنوان Merchant استفاده می‌کند:

zibal

وقتی Sandbox روشن است، درخواست با مقدار zibal ارسال می‌شود؛ حتی اگر Merchant ID واقعی را در تنظیمات ذخیره کرده باشید.

برخلاف زرین‌پال، Sandbox زیبال در تنظیمات اولیه به‌صورت پیش‌فرض خاموش است.

راه‌اندازی Sandbox

1. پنل زیبال را در تنظیمات درگاه‌ها باز کنید.
2. گزینه «فعال‌سازی حالت آزمایشی زیبال» را روشن کنید.
3. تنظیمات را ذخیره کنید.
4. یک محصول آزمایشی با مبلغ بیشتر از حداقل مجاز بسازید.
5. سفارش را از Checkout ثبت و زیبال را انتخاب کنید.
6. انتقال به صفحه پرداخت را بررسی کنید.
7. یک پرداخت موفق آزمایشی انجام دهید.
8. وضعیت، Transaction ID و یادداشت سفارش را کنترل کنید.
9. یک پرداخت لغوشده نیز آزمایش کنید.
10. بازگشت تکراری یا Refresh را بررسی کنید.

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

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

برای انتشار درگاه:

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

وجود Merchant ID واقعی در فیلد تنظیمات به معنی عملیاتی‌بودن درگاه نیست؛ تا زمانی که Sandbox روشن باشد، مقدار zibal برای درخواست استفاده می‌شود.

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

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

{transaction_id}

در نسخه بررسی‌شده، این جای‌نگهدار با trackId زیبال جایگزین می‌شود.

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

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

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

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

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

{fault}

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

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

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

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

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

برای ساخت درخواست، جم پک اطلاعات زیر را برای زیبال ارسال می‌کند:

• Merchant ID یا مقدار آزمایشی zibal؛
• مبلغ سفارش به ریال؛
• URL بازگشت؛
• شناسه عددی سفارش در orderId؛
• توضیح شامل نام و نام خانوادگی صورتحساب و نام و تعداد محصولات؛
• شماره موبایل صورتحساب؛
• ایمیل صورتحساب.

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

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

ریال و تومان

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

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

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

جمع سفارش: 350,000 تومان
مبلغ مورد انتظار زیبال: 3,500,000 ریال

نمونه هزار تومان:

جمع سفارش: 350 هزار تومان
مبلغ مورد انتظار زیبال: 3,500,000 ریال

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

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

Callback زیبال

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

aio_wc_zibal

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

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

یا با توجه به پیوندهای یکتا:

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

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

زیبال هنگام بازگشت این اطلاعات اصلی را در اختیار Callback قرار می‌دهد:

پارامتر	کاربرد
success	اگر برابر 1 باشد، پرداخت برای Verify بررسی می‌شود
trackId	شناسه تراکنش برای Verify
wc_order	شناسه سفارش که جم پک به URL بازگشت افزوده است

اگر پارامتر wc_order نباشد، درگاه شناسه سفارش را از نشست موقت ووکامرس (Session) بازیابی می‌کند. وجود شناسه در نشانی بازگشت کمک می‌کند سفارش حتی بدون نشست فعال مشتری پیدا شود.

Callback باید:

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

مراحل فنی پرداخت

۱. ایجاد سفارش

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

۲. درخواست پرداخت از زیبال

جم پک درخواست JSON را به مسیر زیر ارسال می‌کند:

https://gateway.zibal.ir/v1/request

اگر پاسخ دارای result=100 و یک trackId باشد، درخواست موفق شناخته می‌شود. trackId در متای سفارش ذخیره خواهد شد.

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

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

https://gateway.zibal.ir/start/TRACK_ID

۴. بازگشت از زیبال

اگر success=1 نباشد، تراکنش لغوشده یا ناموفق در نظر گرفته می‌شود. سفارش پرداخت‌شده نمی‌شود و مشتری برای تلاش دوباره به Checkout بازمی‌گردد.

۵. Verify تراکنش

اگر نتیجه اولیه موفق باشد، Merchant و trackId به مسیر زیر ارسال می‌شوند:

https://gateway.zibal.ir/v1/verify

در پاسخ اولیه موفق:

• result=100 به معنی Verify موفق است؛
• مبلغ برگشتی باید با مبلغ سفارش برابر باشد؛
• trackId به‌عنوان Transaction ID ووکامرس استفاده می‌شود؛
• پرداخت در ووکامرس تکمیل می‌شود؛
• سبد خرید فعال، در صورت وجود، خالی می‌شود؛
• یادداشت موفقیت در سفارش ثبت می‌شود؛
• مشتری به صفحه نتیجه سفارش هدایت می‌شود.

۶. تراکنش قبلاً تأییدشده

result=201 یعنی زیبال این trackId را قبلاً Verify کرده است.

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

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

trackId یا refNumber؛ کدام در سفارش ذخیره می‌شود؟

پاسخ Verify زیبال می‌تواند علاوه بر trackId شامل refNumber و اطلاعات دیگری باشد. در نسخه بررسی‌شده:

• Transaction ID سفارش برابر trackId قرار می‌گیرد؛
• پیام موفق {transaction_id} را با trackId جایگزین می‌کند؛
• متای اختصاصی زیبال نیز trackId را نگه می‌دارد؛
• refNumber پاسخ Verify ذخیره نمی‌شود.

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

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

پس از تأیید معتبر تراکنش، ووکامرس پرداخت سفارش را تکمیل می‌کند. ووکامرس بر اساس نوع محصولات وضعیت مناسب را تعیین می‌کند:

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

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

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

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

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

سناریوهای پیشنهادی:

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

چک‌لیست آزمون Sandbox

• Sandbox روشن است؛
• درخواست با Merchant آزمایشی zibal ساخته می‌شود؛
• پاسخ درخواست دارای result=100 و trackId است؛
• مشتری به صفحه پرداخت زیبال منتقل می‌شود؛
• پرداخت موفق Verify می‌شود؛
• مبلغ Verify با مبلغ سفارش برابر است؛
• Transaction ID در سفارش ثبت می‌شود؛
• لغو پرداخت سفارش را پرداخت‌شده نمی‌کند؛
• پیام موفق و ناموفق درست نمایش داده می‌شوند؛
• Refresh باعث کاهش دوباره موجودی یا ارسال دوباره اعلان نمی‌شود؛
• Checkout موبایل و دسکتاپ کار می‌کنند.

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

• Sandbox خاموش است؛
• Merchant ID واقعی و مربوط به همان دامنه ثبت شده است؛
• درگاه در پنل زیبال فعال است؛
• مبلغ سفارش و صفحه پرداخت یکسان‌اند؛
• پرداخت کم‌مبلغ واقعی موفق می‌شود؛
• trackId سفارش در پنل زیبال قابل جست‌وجو است؛
• refNumber و مبلغ تراکنش با سفارش تطبیق دارند؛
• سفارش فقط یک بار تکمیل می‌شود؛
• موجودی و اعلان‌ها فقط یک بار پردازش می‌شوند؛
• لغو و پرداخت ناموفق آزمایش شده‌اند؛
• Callback توسط کش، WAF یا Redirect مختل نمی‌شود.

کدهای نتیجه زیبال

پاسخ درخواست و Verify

کد	مفهوم	اقدام پیشنهادی
100	عملیات موفق	trackId، مبلغ و وضعیت سفارش را بررسی کنید
102	Merchant پیدا نشد	Merchant ID و محیط آزمایشی یا عملیاتی را کنترل کنید
103	Merchant غیرفعال است	وضعیت درگاه را در پنل زیبال بررسی کنید
104	Merchant نامعتبر است	شناسه ذخیره‌شده را دوباره از پنل کپی کنید
105	مبلغ از حداقل مجاز کمتر است	مبلغ سفارش آزمایشی را افزایش دهید
106	Callback نامعتبر است	HTTPS، دامنه و ساختار URL بازگشت را بررسی کنید
113	مبلغ از سقف تراکنش بیشتر است	محدودیت درگاه و مبلغ سفارش را بررسی کنید
201	تراکنش قبلاً Verify شده است	وضعیت فعلی سفارش و پردازش تکراری را کنترل کنید

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

عیب‌یابی

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

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

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

خطای 102، 103 یا 104 دریافت می‌شود

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

خطای حداقل مبلغ 105 دریافت می‌شود

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

خطای Callback با کد 106 دریافت می‌شود

• URL سایت و وردپرس را بررسی کنید؛
• Callback باید با http:// یا ترجیحاً https:// معتبر آغاز شود؛
• دامنه نباید مقدار محلی مانند localhost باشد؛
• پیوندهای یکتا و مسیر WC-API را کنترل کنید؛
• Redirect دامنه، www و HTTPS را بررسی کنید؛
• پارامترهای wc-api و wc_order نباید حذف شوند.

مشتری به صفحه زیبال منتقل نمی‌شود

• گزارش خطای Checkout را ثبت کنید؛
• دسترسی سرور به gateway.zibal.ir روی پورت ۴۴۳ را بررسی کنید؛
• DNS، گواهی TLS، cURL و ساعت سرور را کنترل کنید؛
• مبلغ و Merchant ID را بررسی کنید؛
• یک سفارش ساده بدون تخفیف یا ارسال بسازید؛
• WAF خروجی و محدودیت‌های هاست را بررسی کنید.

پرداخت موفق است اما سفارش پرداخت‌نشده مانده است

• trackId را از URL بازگشت یا پنل زیبال پیدا کنید؛
• مبلغ و نتیجه تراکنش را در پنل زیبال بررسی کنید؛
• یادداشت‌های سفارش را بخوانید؛
• دسترسی Callback و API Verify را کنترل کنید؛
• از حذف success، trackId یا wc_order توسط Redirect جلوگیری کنید؛
• نتیجه عدم تطابق مبلغ را بررسی کنید؛
• وضعیت را فقط پس از تطبیق تراکنش دستی تغییر دهید.

خطای عدم تطابق مبلغ ثبت می‌شود

• واحد پول خود سفارش را بررسی کنید؛
• کدهای IRT، IRHT، IRHR و IRR را کنترل کنید؛
• تخفیف، مالیات و ارسال را در جمع نهایی لحاظ کنید؛
• افزونه‌های چندارزی یا تغییر قیمت را در محیط آزمایشی بررسی کنید؛
• مطمئن شوید مبلغ سفارش پس از انتقال مشتری تغییر نکرده است؛
• سفارش تازه‌ای با قیمت ساده بسازید.

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

اگر success برابر 1 نباشد، جم پک پرداخت را ناموفق یا لغوشده در نظر می‌گیرد، یادداشت خطا ثبت می‌کند و مشتری را به Checkout بازمی‌گرداند.

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

کد 201 دریافت می‌شود

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

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

شماره مرجع refNumber در سفارش دیده نمی‌شود

این رفتار نسخه بررسی‌شده است. سفارش trackId را به‌عنوان Transaction ID ذخیره می‌کند و refNumber پاسخ Verify را نگه نمی‌دارد. تراکنش را با trackId در پنل زیبال پیدا کنید.

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

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

Timeout یا خطای SSL رخ می‌دهد

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

نکات امنیتی و حریم خصوصی

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

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

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

منابع فنی

• وب‌سایت رسمی زیبال و نمونه اتصال درگاه
• مستندات فنی زیبال
• WooCommerce Payment Gateway API
• WooCommerce Plugin API callbacks