آموزش تنظیم درگاه بانکی در پنل نمایندگی دامنه

پیش‌نیازهای تنظیم درگاه بانکی پنل نمایندگی

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

برای انجام این آموزش به موارد زیر نیاز دارید:

• دسترسی به کنترل‌پنل هاست مانند cPanel یا DirectAdmin
• دسترسی به File Manager یا FTP
• دسترسی به پوشه source پنل نمایندگی
• اطلاعات پذیرنده دریافت‌شده از بانک یا شرکت ارائه‌دهنده درگاه
• شناسه یا نام انگلیسی درگاه پرداخت
• فعال‌بودن گواهی SSL روی دامنه پنل
• دسترسی به پنل برای انجام یک تراکنش آزمایشی

مرحله اول: تهیه نسخه پشتیبان از فایل تنظیمات درگاه

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

برای تهیه نسخه پشتیبان، فایل payment.php را دانلود کنید یا یک کپی از آن با نامی مانند نمونه زیر بسازید:

payment-backup.php

مرحله دوم: بازکردن فایل payment.php

تنظیمات درگاه‌های بانکی در فایل payment.php قرار دارد. برای دسترسی به این فایل، وارد File Manager هاست شوید و مسیر زیر را باز کنید:

source/config/payment.php

فایل payment.php را انتخاب کرده و با استفاده از گزینه Edit یا Code Editor آن را باز کنید.

مرحله سوم: پیداکردن نام درگاه بانکی در فایل payment.php

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

Ctrl + F

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

behpardakht

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

مرحله چهارم: واردکردن مشخصات درگاه پرداخت

در بخش مربوط به درگاه انتخاب‌شده، چند پارامتر برای ثبت اطلاعات پذیرنده مشاهده خواهید کرد. مقدار هر پارامتر باید پس از علامت => و بین دو علامت تک‌کوتیشن قرار بگیرد.

ساختار کلی ثبت مقادیر به‌صورت زیر است:

'parameter_name' => 'your_gateway_information',

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

'terminalId' => 'YOUR_TERMINAL_ID',

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

نکات مهم هنگام ویرایش اطلاعات درگاه

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

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

'example' => 'value',

نمونه نامناسب با کوتیشن فارسی یا تغییریافته:

‘example’ => ‘value’,

پارامتر callbackUrl را تغییر ندهید

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

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

تنظیم هزینه تراکنش با پارامتر fee

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

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

'fee' => 'AMOUNT',

به‌جای AMOUNT مقدار مناسب را بر اساس ساختار تعریف‌شده در پنل و شرایط درگاه پرداخت وارد نمایید.

مرحله پنجم: انتخاب درگاه بانکی پیش‌فرض

پس از ثبت مشخصات پذیرنده، باید درگاه موردنظر را به‌عنوان درگاه پیش‌فرض پنل تعیین کنید. برای انجام این کار، در ابتدای فایل payment.php گزینه default را پیدا کنید.

این گزینه معمولاً در خطوط ابتدایی فایل، برای مثال حوالی خط ۱۳، قرار دارد. با این حال شماره خط ممکن است در نسخه‌های مختلف فایل متفاوت باشد؛ بنابراین بهتر است عبارت زیر را جست‌وجو کنید:

'default' =>

مقدار مقابل default را به نام انگلیسی درگاه انتخابی تغییر دهید. برای مثال، برای انتخاب درگاه به‌پرداخت می‌توانید از تنظیم زیر استفاده کنید:

'default' => 'behpardakht',

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

مرحله ششم: آزمایش عملکرد درگاه بانکی

پس از ذخیره فایل payment.php، وارد پنل نمایندگی شوید و یک پرداخت آزمایشی با مبلغ کم انجام دهید. در این آزمایش باید تمام مراحل پرداخت، بازگشت از بانک و ثبت نتیجه تراکنش بررسی شوند.

مواردی که باید در پرداخت آزمایشی بررسی شوند

• نمایش درگاه انتخاب‌شده در پنل
• انتقال صحیح کاربر به صفحه پرداخت بانک
• نمایش صحیح مبلغ پرداخت
• بازگشت کاربر به پنل پس از پرداخت
• ثبت موفق وضعیت تراکنش
• اعمال صحیح اعتبار یا خدمات خریداری‌شده
• محاسبه درست هزینه تراکنش یا fee
• عدم نمایش اطلاعات محرمانه درگاه در صفحه یا پیام خطا

رفع مشکلات رایج تنظیم درگاه پرداخت

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

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

• نام انگلیسی درگاه را در مقدار default بررسی کنید.
• مطمئن شوید نام درگاه دقیقاً مطابق شناسه موجود در فایل است.
• فایل payment.php را ذخیره کرده باشید.
• ساختار PHP فایل و ویرگول انتهای سطرها را بررسی کنید.
• در صورت استفاده پنل از کش تنظیمات، کش برنامه را مطابق مستندات سرویس پاک کنید.

هنگام ورود به صفحه پرداخت خطا نمایش داده می‌شود

این مشکل معمولاً به اطلاعات نادرست پذیرنده یا فعال‌نبودن درگاه مربوط است. موارد زیر را کنترل کنید:

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

پرداخت انجام می‌شود اما تراکنش در پنل تأیید نمی‌شود

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

• بررسی کنید پارامتر callbackUrl تغییر نکرده باشد.
• مطمئن شوید دامنه پنل با HTTPS باز می‌شود.
• از معتبر بودن گواهی SSL اطمینان حاصل کنید.
• تنظیمات دامنه بازگشت را در پنل ارائه‌دهنده درگاه بررسی کنید.
• گزارش خطاهای برنامه و Error Log هاست را مشاهده نمایید.
• مطمئن شوید فایروال هاست درخواست بازگشت درگاه را مسدود نکرده است.

پس از ویرایش payment.php خطای ۵۰۰ نمایش داده می‌شود

خطای ۵۰۰ پس از ویرایش فایل معمولاً به وجود خطای نگارشی در کد PHP مربوط است. موارد زیر را بررسی کنید:

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

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

تغییر درگاه پیش‌فرض اعمال نمی‌شود

اگر با وجود تغییر مقدار default همچنان درگاه قبلی نمایش داده می‌شود، ابتدا صحت نام درگاه را بررسی کنید. سپس کش برنامه، کش سرور و کش مرورگر را پاک نمایید.

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

چک‌لیست نهایی فعال‌سازی درگاه بانکی

قبل از در دسترس قراردادن درگاه برای کاربران، موارد زیر را بررسی کنید:

• از فایل اصلی payment.php نسخه پشتیبان تهیه شده است.
• فایل صحیح در مسیر source/config/payment.php ویرایش شده است.
• اطلاعات پذیرنده در بخش مربوط به درگاه صحیح وارد شده‌اند.
• مقادیر فقط بین تک‌کوتیشن‌های انگلیسی قرار گرفته‌اند.
• نام پارامترها و ساختار اصلی فایل تغییر نکرده‌اند.
• مقدار callbackUrl بدون تغییر باقی مانده است.
• مقدار fee بر اساس سیاست کارمزد درگاه تنظیم شده است.
• نام درگاه در گزینه default به‌درستی وارد شده است.
• گواهی SSL دامنه پنل فعال است.
• پرداخت موفق با مبلغ کم آزمایش شده است.
• بازگشت از بانک و تأیید تراکنش بررسی شده است.
• پرداخت لغوشده یا ناموفق نیز آزمایش شده است.

سؤالات متداول تنظیم درگاه بانکی پنل نمایندگی

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

برای تنظیم درگاه بانکی پنل نمایندگی باید فایل source/config/payment.php را باز کرده و اطلاعات پذیرنده را در بخش مربوط به درگاه موردنظر وارد کنید. مقادیر باید پس از علامت => و بین تک‌کوتیشن‌های انگلیسی قرار بگیرند.

پس از واردکردن مشخصات درگاه، مقدار fee را با توجه به هزینه تراکنش تنظیم کنید و بدون تغییر پارامتر callbackUrl، نام انگلیسی درگاه را در گزینه default قرار دهید. در پایان نیز حتماً یک تراکنش آزمایشی انجام دهید تا انتقال به بانک، بازگشت به پنل و تأیید پرداخت بررسی شود.