راهنمای کامل جداول API درگاه پرداخت بانک مسکن
اتصال به درگاه پرداخت بانکی، یکی از مهمترین مراحل راهاندازی یک کسبوکار آنلاین است. در این میان، داشتن مستندات دقیق و شفاف، فرآیند پیادهسازی را بسیار سادهتر میکند. اگر شما یک توسعهدهنده یا مدیر فنی هستید، حتماً با اهمیت کدهای خطا و پارامترهای API آشنایی دارید. به همین دلیل، ما در این مقاله به صورت جامع جداول راهنما API درگاه پرداخت مسکن را بررسی میکنیم. 🚀
این راهنما به شما کمک میکند تا با درک عمیق کدهای وضعیت و پارامترهای ارسالی و دریافتی، فرآیند اتصال به درگاه را با کمترین خطا و در سریعترین زمان ممکن انجام دهید. در ادامه، تمام جداول مورد نیاز برای یکپارچهسازی موفق را تحلیل خواهیم کرد.
چرا درک جداول راهنمای API درگاه پرداخت مسکن حیاتی است؟
شاید در نگاه اول، این جداول مجموعهای از کدها و پارامترهای فنی به نظر برسند. اما در عمل، آنها نقشه راه شما برای ارتباط با سرورهای بانک هستند. درک صحیح این مستندات مزایای مستقیمی برای کسبوکار شما دارد.
در اینجا به برخی از مهمترین مزیتهای آن اشاره میکنیم:
- 💻 پیادهسازی سریع و بهینه: با دسترسی به این راهنما، زمان مورد نیاز برای توسعه و اتصال به درگاه به شکل چشمگیری کاهش مییابد.
- 🐛 عیبیابی دقیق تراکنشها: در صورت بروز هرگونه خطا، میتوانید به سرعت کد مربوطه را پیدا کرده و مشکل را ریشهیابی کنید.
- 📈 بهبود تجربه کاربری (UX): با مدیریت صحیح خطاها، میتوانید پیامهای مناسبی به کاربر نهایی نمایش دهید و از سردرگمی او جلوگیری کنید.
- 🔒 افزایش امنیت و پایداری: شناخت دقیق پارامترها به شما کمک میکند تا یک ارتباط امن و پایدار با وبسرویس بانک برقرار نمایید.
چگونه API درگاه پرداخت بانک مسکن را فعال کنیم؟
پیش از ورود به جزئیات فنی، ابتدا باید سرویس درگاه پرداخت خود را فعال کنید. فرآیند ثبتنام بسیار ساده است و میتوانید آن را در چند مرحله کوتاه انجام دهید.
- ابتدا به سامانه جامع پذیرندگان بانک مسکن به آدرس
p.api.irمراجعه کنید. - سپس فرم درخواست درگاه پرداخت اینترنتی را با اطلاعات دقیق کسبوکار خود تکمیل نمایید.
- پس از تایید مدارک، اطلاعات کلیدی مانند کد پذیرندگی (Terminal Code)، نام کاربری و رمز عبور برای شما ارسال خواهد شد.
این اطلاعات برای تمام درخواستهای شما به سمت سرورهای بانک ضروری هستند. بنابراین، آنها را در مکانی امن نگهداری کنید.
بررسی جامع جداول راهنما API درگاه پرداخت مسکن
اکنون به بخش اصلی این راهنما میرسیم. در این قسمت، تمام جداول مربوط به پارامترهای ورودی، خروجی و کدهای وضعیت تراکنشها را به تفکیک بررسی میکنیم.
جدول ۱: کدهای وضعیت و خطای تراکنش (Action Codes)
این جدول مهمترین بخش مستندات است. هر پاسخی که از سمت درگاه دریافت میکنید، یک ActionCode دارد که وضعیت تراکنش را مشخص میکند. کد 0 به معنای موفقیتآمیز بودن عملیات و سایر کدها نشاندهنده خطاهای مختلف هستند.
| کد | شرح خطا |
|---|---|
| 0 | Success (موفقیت) |
| -1 | کلید نامعتبر است |
| 1 | صادرکننده کارت از انجام تراکنش صرف نظر کرد. |
| 2 | عملیات تاییدیه این تراکنش قبلا با موفقیت انجام شده است. |
| 5 | از انجام تراکنش صرف نظر شد. |
| 12 | تراکنش نامعتبر است. |
| 14 | شماره کارت ارسالی نامعتبر است. |
| 30 | قالب پیام دارای اشکال است. |
| 33 | تاریخ انقضای کارت سپری شده است. |
| 38 | تعداد دفعات ورود رمز غلط بیش از حد مجاز است. |
| 41 | کارت مفقودی میباشد. |
| 51 | موجودی کافی نیست. |
| 54 | تاریخ انقضای کارت سپری شده است. |
| 55 | رمز دوم (PIN) نامعتبر است. |
| 57 | انجام تراکنش توسط دارنده کارت مجاز نمیباشد. |
| 61 | مبلغ تراکنش بیش از حد مجاز است. |
| 65 | تعداد درخواست تراکنش بیش از حد مجاز است. |
| 75 | تعداد دفعات ورود رمز غلط بیش از حد مجاز است. |
| 96 | بروز خطای سیستمی در انجام تراکنش. |
| 500 | کد پذیرندگی معتبر نمیباشد. |
| 503 | آی پی دامنه کاربر نامعتبر است. |
| 504 | آدرس صفحه برگشت (Callback URL) نامعتبر است. |
| 506 | شماره سفارش تکراری است. |
| 510 | لغو درخواست توسط کاربر. |
| 518 | تراکنش مورد نظر وجود ندارد. |
| 521 | قبلا درخواست تائید با موفقیت ثبت شده است. |
| 600 | لغو تراکنش. |
جدول ۲ و ۳: پارامترهای درخواست ایجاد تراکنش
برای شروع یک پرداخت، باید پارامترهای زیر را به وبسرویس ارسال کنید. در پاسخ، یک RedirectUrl دریافت خواهید کرد که باید کاربر را به آن آدرس هدایت کنید.
پارامترهای ارسالی:
| نام پارامتر | توضیح | نوع |
|---|---|---|
CARDACCEPTORCODE | کد پذیرندگی | string |
USERNAME | نام کاربری | string |
USERPASSWORD | رمز عبور | string |
PAYMENTID | شناسه پرداخت (یکتای شما) | Int64 |
CALLBACKURL | آدرس صفحه برگشت | string |
AMOUNT | مبلغ خرید (به ریال) | Int64 |
پارامترهای دریافتی:
| نام پارامتر | توضیح | نوع |
|---|---|---|
ActionCode | کد پاسخ مطابق جدول ۱ | Int64 |
RedirectUrl | آدرس صفحه پرداخت بانک | string |
جدول ۴: پارامترهای بازگشتی از درگاه به سایت پذیرنده
پس از اتمام عملیات پرداخت توسط کاربر (موفق یا ناموفق)، کاربر به CALLBACKURL شما بازگردانده میشود. در این مرحله، پارامترهای زیر از طریق متد POST به سایت شما ارسال میشوند.
| نام پارامتر | توضیح | نوع |
|---|---|---|
TerminalCode | کد پذیرندگی | Int64 |
RRN | کد پیگیری تراکنش | string |
PaymentID | شناسه پرداخت شما | Int64 |
ActionCode | کد پاسخ نهایی (مطابق جدول ۱) | Int64 |
Amount | مبلغ تراکنش | Int64 |
MessageNumber | شماره پیگیری | Int64 |
جدول ۵ و ۶: پارامترهای تایید تراکنش (Verification)
مهمترین مرحله پس از بازگشت کاربر، تایید تراکنش است. شما باید با ارسال پارامترهای زیر به وبسرویس، از صحت پرداخت اطمینان حاصل کنید. در صورت دریافت ActionCode برابر با 0 در این مرحله، تراکنش قطعی و موفق است.
پارامترهای ارسالی برای تایید:
| نام پارامتر | توضیح | نوع |
|---|---|---|
CARDACCEPTORCODE | کد پذیرندگی | Int64 |
USERNAME | نام کاربری | string |
USERPASSWORD | رمز عبور | string |
RRN | کد پیگیری تراکنش | string |
PAYMENTID | شناسه پرداخت شما | Int64 |
پارامترهای دریافتی پس از تایید:
| نام پارامتر | توضیح | نوع |
|---|---|---|
ActionCode | کد پاسخ نهایی (مطابق جدول ۱) | Int64 |
ErrorDescription | شرح خطا (در صورت وجود) | string |
کاربردهای اصلی API درگاه پرداخت مسکن
استفاده از این API به شما اجازه میدهد تا پرداختهای آنلاین را در انواع پلتفرمها مدیریت کنید. در ادامه چند کاربرد کلیدی آن را مشاهده میکنید:
- 🛒 فروشگاههای اینترنتی: برای فروش محصولات فیزیکی یا دیجیتال و تسویه حساب آنلاین.
- 🎟️ پلتفرمهای خدماتی: برای رزرو نوبت، خرید بلیت، یا پرداخت حق اشتراک سرویسها.
- 🎓 سیستمهای آموزشی آنلاین: جهت پرداخت هزینه دورهها، وبینارها و آزمونها.
- ❤️ موسسات خیریه: برای جمعآوری کمکهای مردمی به صورت آنلاین و شفاف.
جمعبندی نهایی
در این مقاله، جداول راهنما API درگاه پرداخت مسکن را به طور کامل بررسی کردیم. اکنون شما یک مرجع دقیق از کدهای خطا، پارامترهای درخواست، تایید و بازگشت تراکنش در اختیار دارید. با استفاده صحیح از این مستندات، میتوانید فرآیند یکپارچهسازی درگاه پرداخت را با اطمینان و سرعت بیشتری انجام دهید. به خاطر داشته باشید که مرحله تایید تراکنش (Verification) برای جلوگیری از هرگونه سوءاستفاده مالی ضروری است.
آیا تجربه کار با این API را داشتهاید؟ کدام کد خطا برای شما چالشبرانگیز بود؟ نظرات و سوالات خود را در بخش دیدگاهها با ما در میان بگذارید. 💬