راهنمای پلاگین «اپن‌کارت» ایران درگاه

irandargah-opencart.md

افزونهٔ ایران‌درگاه برای اپن‌کارت

افزونهٔ رسمی اتصال فروشگاه اپن‌کارت به درگاه پرداخت ایران‌درگاه (IPG v2).

به‌دلیل تفاوت ساختاری و namespace میان اپن‌کارت ۳ و ۴، دو نسخهٔ مجزا ارائه شده است:

نسخه	پوشه	وضعیت
OpenCart 3.x	(opencart3/)	✅ آماده
OpenCart 4.x	(opencart4/)	✅ آماده

---

✨ امکانات (هر دو نسخه)

• پرداخت با تأیید قطعی سمت سرور (/v2/verifications) و مقایسهٔ مبلغ — بدون direct_verify.
• هدایت Referer-safe: صفحهٔ واسطِ standalone روی دامنهٔ فروشگاه با Referrer-Policy: origin.
• محیط Sandbox/Production، امضای درخواست (HMAC)، تبدیل خودکار واحد پول.
• جدول اختصاصی پیگیری تراکنش (PREFIX_irandargah_transaction) با توکن ضدِ دستکاری.
• مدیریت امن خطای شبکهٔ پس از پرداخت (وضعیت «در انتظار بررسی»).

---

⚙️ نصب (OpenCart 3.x)

1. محتوای پوشهٔ (opencart3/upload/) را در ریشهٔ نصب اپن‌کارت کپی کنید (ساختار admin/, catalog/, system/ با نصب شما ادغام می‌شود).
2. از مسیر Extensions › Extensions › Payments، ماژول IranDargah را نصب و ویرایش کنید.
3. توکن API، محیط، واحد مبلغ و وضعیت‌های سفارش را تنظیم کنید.
4. در پنل ایران‌درگاه، دامنهٔ فروشگاه را به‌عنوان دامنهٔ مجاز ترمینال ثبت کنید. ⚠️ الزامی.

⚙️ نصب (OpenCart 4.x)

1. پوشهٔ (opencart4/extension/) را در مسیر extension/ نصب اپن‌کارت کپی کنید (یا یک ZIP شامل install.json و پوشهٔ extension/irandargah/ بسازید و از «Extensions › Installer» بارگذاری کنید).
2. از Extensions › Extensions › Payments، ماژول IranDargah را نصب و ویرایش کنید.
3. تنظیمات را مانند نسخهٔ ۳ وارد کنید.

🧪 تست

محیط را «آزمایشی» بگذارید و با کارت تستی 6037997123456789 (CVV2 123، انقضا 05/12) پرداخت کنید.

🛠️ عیب‌یابی

• گزارش‌ها: System › Maintenance › Error Logs فایل irandargah.log.
• خطای دامنه هنگام هدایت → دامنهٔ ثبت‌شدهٔ ترمینال را بررسی کنید.
• مبلغ ۱۰ برابر/یک‌دهم → «واحد مبلغ ارسالی» را دستی تنظیم کنید.

مجوز

GPL-2.0-or-later