راهنمای کاربر

شروع سریع

اگر می‌خواهید سریع‌ترین مسیر را برای راه‌اندازی طی کنید، این چهار قدم را دنبال کنید:

1. دانلود و نصب فایل افزونه را از پنل کاربری راست‌چین دانلود کرده و در پیشخوان وردپرس به مسیر «افزونه‌ها ← افزودن ← بارگذاری افزونه» بروید.
2. فعال‌سازی لایسنس پس از فعال‌سازی، دامنه سایت را در پنل راست‌چین ثبت کنید.
3. وارد کردن اطلاعات بانک به تنظیمات افزونه (ووکامرس یا Gravity Forms) رفته و اطلاعات Terminal ID، نام کاربری و رمز عبور را وارد کنید.
4. تست تراکنش یک سفارش آزمایشی ایجاد کرده و فرآیند کامل پرداخت را تست کنید.

نصب و فعال‌سازی

پیش‌نیازها

• وردپرس نسخه ۵.۰ یا بالاتر
• PHP نسخه ۷.۴ یا بالاتر
• حداقل یکی از: WooCommerce ۵.۰+ یا Gravity Forms ۲.۵+
• لایسنس معتبر از راست‌چین

روش نصب

1. دانلود فایل افزونه وارد پنل کاربری راست‌چین شوید و فایل ZIP افزونه را دانلود کنید.
2. بارگذاری در وردپرس از مسیر پیشخوان ← افزونه‌ها ← افزودن ← بارگذاری افزونه فایل ZIP را آپلود کنید.
3. فعال‌سازی افزونه پس از نصب، روی دکمه «فعال‌سازی افزونه» کلیک کنید.

فعال‌سازی لایسنس

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

1. ورود به پنل راست‌چین به rtl-theme.com رفته و وارد حساب کاربری شوید.
2. مدیریت دامنه به بخش «خرید‌های من» رفته و افزونه را پیدا کنید. روی «مدیریت دامنه» کلیک کرده و آدرس سایت خود را وارد کنید (بدون https:// و بدون / پایانی).
3. ذخیره و بازگشت به سایت پس از ثبت دامنه، صفحه افزونه را در پیشخوان وردپرس refresh کنید. پیام خطا برطرف می‌شود.

تنظیمات WooCommerce

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

اطلاعات اصلی بانک

تنظیمات رفتاری

تنظیمات نمایش

ارزها

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

داشبورد ووکامرس

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

کارت‌های KPI

• درآمد دوره — مجموع تراکنش‌های موفق در بازه انتخابی
• نرخ موفقیت — درصد تراکنش‌های موفق نسبت به تراکنش‌های شکست‌خورده
• میانگین مبلغ — متوسط مبلغ تراکنش‌های موفق
• تراکنش‌های موفق — تعداد کل تراکنش‌های پرداخت‌شده
• استرداد آنلاین — مجموع مبلغ استردادشده + تعداد دفعات
• درآمد لینک‌های پرداخت — درآمد ناشی از لینک‌های اختصاصی

بازه زمانی

می‌توانید بین بازه‌های پیش‌فرض (۷، ۳۰، ۹۰، ۱۸۰، ۳۶۵ روز) یا «بازه دلخواه» با date picker انتخاب کنید.

اکسپورت CSV

با کلیک روی دکمه «اکسپورت CSV»، فایل تمام تراکنش‌های بازه انتخابی دانلود می‌شود (تا سقف ۵۰،۰۰۰ رکورد) با BOM UTF-8 برای نمایش صحیح فارسی در Excel.

پاک‌سازی دیتا

غیرفعال‌سازی آمار

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

لینک پرداخت اختصاصی

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

ساخت لینک جدید

1. ورود به صفحه لینک‌ها از منوی درگاه ملت ← لینک‌های پرداخت روی دکمه «افزودن جدید» کلیک کنید.
2. تکمیل اطلاعات عنوان، توضیحات، مبلغ (تومان یا ریال)، سقف استفاده (اختیاری)، تاریخ انقضا (اختیاری) را وارد کنید.
3. انتخاب فیلدهای دریافت مشخص کنید چه اطلاعاتی از مشتری دریافت شود: نام، ایمیل، موبایل، یادداشت.
4. ذخیره و کپی URL پس از ذخیره، در صفحه جزئیات لینک، URL یکتا (مثل https://shop.com/pay/abc123def456) و QR Code آن قابل کپی است.

تنظیمات پیشرفته لینک

آمار per-link

در صفحه جزئیات هر لینک، اطلاعات زیر را می‌بینید:

• تعداد بازدید + شروع پرداخت + پرداخت موفق
• نرخ تبدیل (Conversion Rate)
• مجموع درآمد ناشی از این لینک
• لیست تمام سفارش‌های ایجادشده از این لینک

نکته فنی

URL لینک از rewrite rule استفاده می‌کند. اگر بعد از نصب لینک‌ها ۴۰۴ می‌دهند، یک بار به تنظیمات ← پیوندهای یکتا رفته و روی «ذخیره تغییرات» کلیک کنید.

استرداد آنلاین (ووکامرس)

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

فعال‌سازی

به دلیل حساسیت بسیار بالا، این قابلیت به‌صورت پیش‌فرض غیرفعال است. برای فعال‌سازی:

1. وارد تنظیمات گیت‌وی شوید — مسیر ووکامرس ← تنظیمات ← پرداخت‌ها ← به پرداخت ملت
2. بخش «تنظیمات استرداد آنلاین» را پیدا کنید
3. تیک «فعال‌سازی استرداد آنلاین» را بزنید و تنظیمات را ذخیره کنید

انجام استرداد

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

دو حالت استرداد

• استرداد به کارت اصلی: مبلغ به همان کارتی که مشتری پرداخت کرده برمی‌گردد. (نیازی به دانستن شماره کارت ندارید.)
• استرداد به کارت دلخواه: مبلغ به شماره کارت دیگری برگردانده می‌شود (مثلاً وقتی مشتری کارت اصلی را از دست داده).

مراحل

1. انتخاب نوع استرداد (کارت اصلی یا دلخواه)
2. وارد کردن مبلغ — می‌تواند کمتر از مبلغ سفارش باشد (استرداد جزئی)
3. دلیل استرداد (اختیاری ولی توصیه می‌شود)
4. کلیک روی «ثبت استرداد»
5. تأیید اول با کلیک OK روی پنجره confirm
6. تأیید دوم با تایپ دستی عبارت REFUND (انگلیسی، حروف بزرگ)

تاریخچه استرداد

در همین متاباکس، تاریخچه تمام استردادهای انجام‌شده (موفق و ناموفق) با تاریخ و کد خطا قابل مشاهده است.

استرداد جزئی و چندبار

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

شناسه پرداخت (Bill ID)

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

۴ حالت پیکربندی

تنظیمات حالت checkout

اگر حالت checkout را انتخاب کنید، می‌توانید این موارد را شخصی‌سازی کنید:

• برچسب فیلد — مثل «شماره دانشجویی»
• متن راهنما — متن راهنمای داخل فیلد
• الگوی اعتبارسنجی (عبارت باقاعده) — مثل ^\d{10}$ برای ۱۰ رقم (بدون جداکننده)
• اجباری بودن — مشتری بدون پر کردن نتواند پرداخت کند

مثال حالت auto

برای استخراج خودکار شناسه از meta سفارش:

add_filter('am_mellat_payer_id', function($default, $order) {
    return $order->get_meta('_student_id') ?: $default;
}, 10, 2);

ذخیره کارت در درگاه بانک

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

نحوه فعال‌سازی

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

چگونه کار می‌کند؟

1. افزونه شماره موبایل مشتری (از فیلد billing phone) را به همراه RefId به صفحه startpay.mellat ارسال می‌کند.
2. در اولین خرید، مشتری شماره کارت کامل را وارد می‌کند و بانک می‌پرسد «ذخیره شود؟».
3. در خریدهای بعدی، لیست کارت‌های ذخیره‌شده در صفحه بانک ظاهر می‌شود و مشتری فقط CVV2 وارد می‌کند.

تنظیمات Gravity Forms

اگر Gravity Forms نصب است، یک ماژول مستقل به‌صورت خودکار فعال می‌شود. این ماژول حتی بدون نصب ووکامرس هم کار می‌کند.

تنظیمات سراسری

به مسیر Forms ← Settings ← درگاه ملت بروید و این تنظیمات را انجام دهید:

ساخت Feed برای فرم

برای هر فرم Gravity Forms که می‌خواهید پرداخت دریافت کند، باید یک Feed بسازید.

1. ورود به تنظیمات فرم فرم خود را در Gravity Forms باز کنید و به تب Settings ← Mellat بروید.
2. افزودن Feed جدید روی «Add New» کلیک کنید.
3. تنظیمات Feed موارد زیر را تکمیل کنید:
   • نام Feed — نام دلخواه برای شناسایی
   • نوع تراکنش — «محصولات و خدمات» (پیش‌فرض)
   • مبلغ پرداخت — انتخاب از: «مجموع کل فرم» یا یکی از فیلدهای price/total/number/product
   • اطلاعات مشتری — مپ فیلدهای name/email/phone از فرم به addon (اختیاری ولی توصیه می‌شود)
4. Conditional Logic (اختیاری) می‌توانید شرط بگذارید که Feed فقط در صورت برقراری شرایطی اجرا شود.
5. ذخیره Feed آماده است. حالا هر بار فرم submit شود، addon redirect به بانک را مدیریت می‌کند.

فرآیند پرداخت

1. کاربر فرم را پر و submit می‌کند.
2. GF Entry ایجاد می‌شود.
3. addon در پشت صحنه bpPayRequest را به بانک می‌فرستد.
4. کاربر به یک صفحه واسط می‌رود که خودکار به startpay.mellat POST می‌کند.
5. کاربر در صفحه بانک پرداخت می‌کند.
6. بانک callback به سایت می‌زند، addon verify/inquiry/settle انجام می‌دهد.
7. Entry با وضعیت Paid یا Failed به‌روزرسانی می‌شود.
8. کاربر به صفحه نتیجه (موفق/ناموفق) با پیام سفارشی هدایت می‌شود.

داشبورد Gravity Forms

داشبورد آماری مستقل برای ماژول GF در مسیر Forms ← آمار درگاه ملت در دسترس است.

تفاوت با داشبورد ووکامرس

• جدول دیتای مستقل از WC (در wp_am_mellat_gf_transactions)
• به جای «مشتری‌های برتر»، «فرم‌های پربازده» نمایش داده می‌شود
• لینک «مشاهده» به Entry Detail در GF می‌رود، نه سفارش WC

اطلاعات نمایش‌داده‌شده

• ۵ کارت KPI: درآمد، نرخ موفقیت، میانگین مبلغ، تراکنش‌های موفق، استرداد
• نمودار درآمد روزانه
• توزیع کد خطاهای بانک
• ساعات اوج پرداخت
• آمار فنی (Native vs nusoap، میانگین زمان پاسخ بانک)
• ۲۰ تراکنش اخیر با لینک به Entry
• ۱۰ فرم پربازده بر اساس مجموع پرداخت

استرداد آنلاین (Gravity Forms)

سیستم استرداد آنلاین برای GF کاملاً مستقل از ماژول WC است.

فعال‌سازی

1. به Forms ← Settings ← درگاه ملت بروید
2. تیک «فعال‌سازی استرداد آنلاین» را بزنید
3. تنظیمات را ذخیره کنید

انجام استرداد

وارد Forms ← Entries شوید، روی Entry موردنظر کلیک کنید. در ستون کناری، متاباکس «استرداد آنلاین درگاه ملت» را خواهید دید.

مراحل دقیقاً مشابه ماژول WC است (انتخاب نوع، وارد کردن مبلغ، تأیید دو مرحله‌ای با تایپ REFUND).

عیب‌یابی

به درگاه بانک منتقل نمی‌شوم

• گزینه «فعال‌سازی Debug» را در تنظیمات روشن کنید.
• یک تراکنش تست بزنید — کد خطا در صفحه پیش‌فاکتور نمایش داده می‌شود.
• مطابق کد خطا (مثل 24 = اطلاعات کاربری نامعتبر) اقدام کنید.

پرداخت موفق بود ولی سفارش ناموفق ثبت شد

• به ووکامرس ← Status ← Logs رفته و log با source am-mellat را بررسی کنید.
• معمولاً مشکل در بخش bpVerifyRequest یا bpSettleRequest است.

لینک پرداخت ۴۰۴ می‌دهد

• به تنظیمات ← پیوندهای یکتا بروید و «ذخیره تغییرات» را بزنید.
• این عمل rewrite rules را تازه می‌کند.

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

• مطمئن شوید گزینه «فعال‌سازی استرداد آنلاین» در تنظیمات روشن است (پیش‌فرض غیرفعال).
• سفارش باید با درگاه ملت پرداخت شده باشد و حداقل یک تراکنش موفق ثبت‌شده باشد.

SoapClient extension روی سرور نیست

افزونه به‌صورت خودکار به nusoap fallback می‌کند. در داشبورد بخش «آمار فنی» می‌توانید ببینید کدام backend استفاده می‌شود.

خطای «لایسنس نامعتبر»

• دامنه را در پنل راست‌چین ثبت کنید.
• اگر دامنه شامل www. است، هر دو نسخه (با و بدون www) را امتحان کنید.
• cache افزونه‌های caching را پاک کنید.

کدهای خطای متداول بانک ملت

سؤالات متداول

آیا یک لایسنس برای WC و GF کافی است؟

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

اگر بعد از فعال‌سازی، ووکامرس را نصب کنم چه؟

افزونه به‌طور خودکار ماژول WC را فعال می‌کند و rewrite rules را تازه می‌کند. ممکن است یک بار refresh لازم باشد.

چگونه می‌توانم لاگ‌ها را ببینم؟

برای ماژول WC به ووکامرس ← Status ← Logs بروید و فایل با source am-mellat را باز کنید. برای GF نیز همان log فعال است.

آیا backup گرفته شود قبل از نصب؟

بله، همیشه قبل از نصب هر افزونه جدید روی سایت تولیدی، یک backup کامل بگیرید.

آیا این افزونه مالیات/شیپینگ را تحت تأثیر قرار می‌دهد؟

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

اگر سرور SSL نداشته باشد چه؟

بانک ملت callback را روی هر دو http و https قبول می‌کند، ولی برای امنیت کلی فروشگاه، حتماً SSL نصب کنید.

چگونه دیتای آماری را backup بگیرم؟

از دکمه «اکسپورت CSV» در داشبورد استفاده کنید. یا کل جدول wp_am_mellat_transactions (و wp_am_mellat_gf_transactions برای GF) را با phpMyAdmin export کنید.

پشتیبانی فنی چگونه است؟

از طریق پنل کاربری راست‌چین تیکت ارسال کنید.