راهنمای کامل متدهای وب سرویس درگاه بانک مسکن (API)

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

چرا وب سرویس درگاه بانک مسکن را انتخاب کنیم؟

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

✅ امنیت بالا: تراکنش‌ها بر بستر امن شبکه شاپرک انجام می‌شوند. این موضوع خیال شما و مشتریانتان را راحت می‌کند.
⚙️ یکپارچه‌سازی آسان: مستندات واضح و فرآیندهای استاندارد، اتصال به درگاه را برای توسعه‌دهندگان ساده کرده است.
📈 پایداری و سرعت: زیرساخت قدرتمند بانک مسکن، پایداری سرویس و سرعت بالای انجام تراکنش‌ها را تضمین می‌کند.
📄 پشتیبانی فنی: تیم پشتیبانی ناواکو (مجری فنی) آماده پاسخگویی به سوالات و مشکلات احتمالی شماست.
🔄 مدیریت کامل تراکنش: با متدهای موجود، شما کنترل کاملی بر روی تأیید یا لغو تراکنش‌ها خواهید داشت.

پیش‌نیازهای فنی برای اتصال به درگاه

قبل از شروع کدنویسی، باید با الزامات فنی درگاه آشنا باشید. این موارد برای برقراری ارتباط صحیح با سرور ضروری هستند. تمامی تبادلات اطلاعاتی باید طبق اصول زیر انجام شوند:

پروتکل ارتباطی: تمام درخواست‌ها از طریق پروتکل HTTP 1.1 و با متد POST ارسال می‌شوند.
فرمت داده‌ها: کلیه اطلاعات ارسالی و دریافتی باید با فرمت Json-UTF8 باشند.
هدرهای (Headers) ضروری: نرم‌افزار شما باید در هر درخواست، هدرهای زیر را ارسال کند:

Content-Type: application/json
Accept: application/json

آدرس IP ثابت: درخواست‌های شما باید حتماً از آدرس IP ثبت‌شده در سیستم ارسال شوند. در غیر این صورت، سرور به آن‌ها پاسخ نخواهد داد.

مراحل کامل یک تراکنش موفق با متدهای وب سرویس

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

گام اول: ایجاد درخواست پرداخت (متد PayRequest)

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

آدرس سرور تست: http://79.174.161.132:8181/NvcService/Api/v2/PayRequest
آدرس سرور عملیاتی: https://fcp.shaparak.ir/NvcService/Api/v2/PayRequest

در صورت موفقیت‌آمیز بودن درخواست، خروجی شامل دو بخش اصلی است:

ActionCode: یک کد وضعیت که باید آن را ذخیره کنید. مقدار 0 به معنی موفقیت است.
RedirectUrl: آدرس صفحه پرداخت که باید کاربر را فوراً به آن هدایت (Redirect) کنید.

نکات مهم:

شناسه پرداخت (PAYMENTID) در هر درخواست باید کاملاً یکتا باشد.
آدرس بازگشت (CallBackUrl) بهتر است به جای IP، آدرس دامنه سایت شما باشد.
لینک پرداخت دریافت شده حساس به حروف کوچک و بزرگ (Case-sensitive) است.

گام دوم: هدایت کاربر و دریافت نتیجه (CallBack)

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

در این مرحله، شما باید ActionCode موجود در اطلاعات بازگشتی را بررسی کنید.

اگر ActionCode برابر با 0 بود: یعنی تراکنش از سمت بانک موفق بوده است. حالا شما باید آن را نهایی کنید.
اگر ActionCode مقداری غیر از 0 داشت: یعنی تراکنش ناموفق بوده و نیازی به انجام مراحل بعدی نیست.

گام نهایی: تأیید یا بازگشت تراکنش (متدهای Confirm و Reverse)

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

۱. متد تأیید تراکنش (Confirm)

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

آدرس سرور تست: http://79.174.161.132:8181/NvcService/Api/v2/Confirm
آدرس سرور عملیاتی: https://fcp.shaparak.ir/NvcService/Api/v2/Confirm

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

۲. متد بازگشت وجه (Reverse)

این متد برای لغو کردن تراکنش و بازگرداندن پول به مشتری استفاده می‌شود. معمولاً زمانی کاربرد دارد که به دلیل مشکلات فنی (مانند اتمام موجودی کالا) نمی‌توانید خدمات را ارائه دهید.

آدرس سرور تست: http://79.174.161.132:8181/NvcService/Api/v2/Reverse
آدرس سرور عملیاتی: https://fcp.shaparak.ir/NvcService/Api/v2/Reverse

شما تنها می‌توانید تراکنش‌هایی را Reverse کنید که هنوز Confirm نشده‌اند.

کاربردهای درگاه پرداخت بانک مسکن

وب سرویس درگاه پرداخت بانک مسکن برای طیف وسیعی از کسب‌وکارها مناسب است. انعطاف‌پذیری این API آن را به یک انتخاب هوشمندانه تبدیل کرده است. 💡

🛒 فروشگاه‌های اینترنتی: برای فروش آنلاین کالا، از پوشاک و لوازم الکترونیکی گرفته تا محصولات دیجیتال.
🎓 پلتفرم‌های آموزشی: برای فروش دوره‌های آنلاین، وبینارها و محتوای آموزشی.
🎟️ سرویس‌های خدماتی: برای رزرو آنلاین بلیط، هتل، تورهای مسافرتی یا خدمات تخصصی.
🧾 پرداخت قبوض و شارژ: برای وب‌سایت‌ها و اپلیکیشن‌های ارائه‌دهنده خدمات پرداخت.
🤝 موسسات خیریه: برای جمع‌آوری کمک‌های مردمی به صورت آنلاین و شفاف.

چگونه برای دریافت درگاه اقدام کنیم؟ (مراحل ثبت‌نام)

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

مراجعه به وب‌سایت: ابتدا به سامانه جامع پذیرندگان آپی به آدرس p.api.ir مراجعه کنید.
تکمیل فرم ثبت‌نام: اطلاعات هویتی و اطلاعات کسب‌وکار خود را با دقت وارد نمایید.
بارگذاری مدارک: مدارک مورد نیاز مانند تصویر کارت ملی و مجوزهای کسب‌وکار (در صورت وجود) را آپلود کنید.
احراز هویت: پس از بررسی اولیه، مراحل احراز هویت انجام خواهد شد.
دریافت اطلاعات اتصال: در نهایت، اطلاعات کلیدی برای اتصال به وب سرویس (مانند ترمینال آیدی) در اختیار شما قرار می‌گیرد.

راهنمای کامل شما برای متدهای درگاه مسکن

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