راهنمای پلاگین «پرستاشاپ» ایران درگاه

irandargah-prestashop.md

ماژول ایران‌درگاه برای پرستاشاپ

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

ماژولِ آمادهٔ نصب در پوشهٔ (irandargahpayment/) قرار دارد.

---

✨ امکانات

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

🧱 ساختار

irandargahpayment/
├── irandargahpayment.php        کلاس اصلی ماژول (نصب/هوک‌ها/تنظیمات/استرداد)
├── config.xml
├── classes/IranDargahApi.php    کلاینت API نسخهٔ ۲ (cURL، امضا، idempotency)
├── controllers/front/
│   ├── redirect.php             ایجاد تراکنش + صفحهٔ هدایت Referer-safe
│   └── callback.php             بازگشت، تأیید سمت سرور، ساخت سفارش
└── views/
    ├── templates/front/         قالب‌های خطا و نتیجه
    └── img/irandargah.svg

⚙️ نصب

1. پوشهٔ irandargahpayment/ را در مسیر modules/ فروشگاه پرستاشاپ کپی کنید (یا از همین پوشه یک ZIP بسازید و از «ماژول‌ها › بارگذاری ماژول» نصب کنید).
2. ماژول درگاه پرداخت ایران‌درگاه را نصب و پیکربندی کنید.
3. توکن API، محیط و واحد مبلغ را تنظیم کنید.
4. در پنل ایران‌درگاه، دامنهٔ فروشگاه را به‌عنوان دامنهٔ مجاز ترمینال ثبت کنید. ⚠️ الزامی.

🧪 تست (Sandbox)

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

🛠️ عیب‌یابی

• خطای دامنه هنگام هدایت: دامنهٔ فروشگاه با دامنهٔ ثبت‌شدهٔ ترمینال یکی نیست.
• مبلغ اشتباه (۱۰ برابر): «واحد مبلغ ارسالی» را دستی روی ریال/تومان تنظیم کنید.
• استرداد ۴۰۳: قابلیت استرداد روی ترمینال فعال نیست؛ با پشتیبانی ایران‌درگاه تماس بگیرید.
• گزارش‌ها در پارامترهای پیشرفته › گزارش‌ها (Logs) با پیشوند [IranDargah].

مجوز

GPL-2.0-or-later