برخی متدهای API درگاه پرداخت بانک مسکن
در مقاله قبل در مورد معرفی وب سرویس درگاه پرداخت بانک مسکن صحبت کردیم در این مقاله متدهای وب سرویس درگاه بانک مسکن مورد بررسی قرار میدهیم
توابع
تمامی تبادل اطلاعات برپایه پروتکل 1/1 HTTP و متد POST انجام میشود، کلیه اطلاعات ارسالی و دریافتی فرمت
Json-UTF8 داشته و نرم افزار پذیرنده باید در هنگام اتصال Header-Http های زیر را ارسال نماید:
Content-Type: application/json
Accept: application/json
تمامی درخواست های ارسالی پذیرنده باید از Address-IP از قبل اعلان شده و ثبت شده انجام شود.
متد درخواست تراکنش پرداخت PayRequest
آدرس فراخوانی این سرویس :
سرور تست:
http://79.174.161.132:8181/NvcService/Api/v2/PayRequest
سرور عملیاتی :
https://fcp.shaparak.ir/NvcService/Api/v2/PayRequest
با استفاده از این متد، پذیرنده درخواست انجام یک تراکنش را از ناواکو مینماید. در صورتی که صحت اعتبارپذیرنده تأیید شود )بوسیله ارسال پارامترهای ورودی(، آدرس یکتایی برای او صادر و ارسال میگردد
پارامتر ورودی متد درخواست تراکنش پرداخت یک شئ با صفت هایی به شرح جدول شماره 2 میباشد، که پس از تبدیل به Json به وب سرویس ارسال خواهد شد
مقدار بازگشتی از این سرویس یک شی Json با صفت هایی به شرح جدول شماره 3 می باشد.
قسمت اول یک کد پاسخ است که در این سند به آن ActionCode میگوییم. جدول شماره 1
قسمت دوم آدرس صفحه پرداخت است که برنامه پذیرنده باید به این آدرس Redirect-HTTP کند.
پذیرنده موظف است مقدار بازگشتی ActionCode را ذخیره کرده و در صورتی که این مقدار برابر با . باشد، به آدرس سایت دروازه پرداخت Redirect نماید.
آدرس Redirect دریافتی موقتی بوده وبرای مدت کوتاهی معتبر است و پذیرنده به محض دریافت می بایست مرورگر را به آدرس دروازه پرداخت Redirect نماید.
** در صورت بازگشت مقداری غیر از . در ActionCode ، آدرس دروازه پرداخت خالی خواهد بود و با توجه به کد بازگشتی طبق جدول شماره 1 پذیرنده از مشکل پیش آمده مطلع می گردد. پذیرنده میتواند برای یک آدرس جدید ، این متد را مجدداً فراخوانی نماید.
** در هر درخواست پذیرنده، باید شناسه پرداخت ارسالی )PAYMENTID )یکتا باشد و در غیر این صورت مسئولیت آن به عهده پذیرنده میباشد.
تبصره 1- در ارسال CallBackUrl حتی الامکان از آدرس Domain به جای شماره IP استفاده شود.
تبصره 2 – آدرس Redirect دریافت شده حساس به کاراکتر است و می بایست بدون تغییر و دقیقا به آدرس مورد نظر Redirect شود. در اصطلاح Sensitive Case می باشد.
تبصره 3 – شکل حروف و قالب نگارش پارامترها و مقادیر آنها باید دقیقا مطابق آنچه در جدولها موجود است درج شود.
تبصره 4 – در صورتی که آدرس آی پی CallBackUrl با آدرس ای پی سایت متفاوت باشد ، پذیرنده می بایست در هنگام ثبت نام و یا قبل از پیاده سازی ادرس آی پی را به شرکت اطلاع دهد و همچنین در صورت تغییر این آدرس در هر زمان می بایست اطلاعات جدید را به شرکت فناوری اطلاعات ناواکو اعلام نمایند .
رسید پرداخت وجه
بعد از تائید درخواست پرداخت از سمت وب سرویس، سایت پذیرنده خریدار را به صفحه درگاه پرداخت هدایت مینماید تا خریدار با ورود اطلاعات کارت بانکی خود در صفحهپرداخت و با انتخاب دکمه پرداخت، اقدام به پرداخت نماید.
پس از انجام مراحل پرداخت وجه، خریدار به صورت خودکار به صفحه تکمیل فرآیند خرید هدایت شده که اطلاعاتی از قبیل اطلاعات پذیرنده، اطلاعات تراکنش، نتیجه تراکنش و شماره پیگیری و … قابل رویت بوده و می تواند خرید خود را تکمیل کند با انتخاب دکمه تکمیل فرآیند خرید و یا بعد از گذشت 05 ثانیه. بعد از تکمیل خرید، مرورگر خریدار به همراه اطلاعات تراکنش به سایت پذیرنده (به آدرس CallBack )هدایت می شود.
این اطلاعات با نام “Data “و به فرمت json توسط مرورگر)Multipart-HTTP ) منتقل میشود که محتویات آن مطابق
جدول 4 خواهد بود.
توضیح 0 -توجه: بعد از اینکه خریدار به سایت پذیرنده که با عنوان CallBack معرفی شده است هدایت شد، پذیرنده موظف است تراکنش را تعیین تکلیف نماید . و برای تکمیل خرید متد تائید (Confirm ) را فراخوانی نماید و یا به دلایلی ( اتمام موجودی کالا و یا خدمات ) متد بازگشت (Reverse ) خرید را فراخوانی نماید .
** در صورتی که مقدار ActionCode بازگشتی از صفحه رسید دیجیتال برابر. )عدد صفر( باشد به معنی نیاز به تایید تراکنش سمت بانک است و پذیرنده باید از متد Confirm استفاده کند تا عملیات پرداخت با موفقیت به اتمام برسد.
** در صورتی که مقدار بازگشتی پارامتر ActionCode مقداری غیر از . )عدد صفر( باشد دیگر نیازی به فراخوانی متد بعدی Confirm یا Reverse نیست و پذیرنده می بایست پیغام خطای مناسب را به مشتری نمایش دهد.
متد تائید تراکنش Confirm
آدرس فراخوانی این سرویس :
سرور تست:
http://79.174.161.132:8181/NvcService/Api/v2/Confirm
سرور عملیاتی :
https://fcp.shaparak.ir/NvcService/Api/v2/Confirm
این متد برای نهایی کردن تراکنش خرید می باشد.
توضیح 2 -توجه: بعد از ارسال اطلاعات تراکنش از صفحه رسید دیجیتال به سایت پذیرنده، پذیرنده زمان محدودی (حدود 5 دقیقه) مهلت دارد که متد Confirm را برای نهایی کردن خرید فراخوانی کند. در صورتی که پذیرنده تا 5 دقیقه Confirm را فراخوانی نکند، بانک بصورت خودکار مبلغ تراکنش را به حساب خریدار برگشت میدهد.
پارامتر ورودی این متد یک نمونه از کلاس InquaryConfirm ( جدول شماره 5 ) می باشد.
مقدار بازگشتی از این متد یک نمونه از کلاس ConfirmResponse( جدول شماره 6 )می باشد.
** خروجی ActionCode برابر با صفر متد فوق، به معنی اتمام موفقیت آمیز و نهایی شدن تراکنش است و میتواند معیار نهایی عملکرد پرداخت توسط کاربر باش
متد برگشت وجه Reverse
آدرس فراخوانی این سرویس :
سرور تست:
http://79.174.161.132:8181/NvcService/Api/v2/Reverse
سرور عملیاتی :
https://fcp.shaparak.ir/NvcService/Api/v2/Reverse
این متد برای برگشت مبلغ خرید به حساب خریدار می باشد.
این متد زمانی کاربرد می یابد که پذیرنده به هر دلیلی از نتیجه متد تایید تراکنش Confirm مطلع نگردد. که در این صورت پذیرنده به دلیل روشن نبودن وضعیت پرداخت، از ارایه خدمت به مشتری امتناع می ورزد و با استفاده از این متد، به بانک درخواست می دهد که در صورتی که مبلغ آن تراکنش از حساب دارنده کارت کسر شده است، آن را برگشت بزند. بازگشت خرید فقط برای درخواست هایی که درخواست تائید نهایی )Confirm )آنها ارسال نشده قابل فراخوانی می باشد .
پارامتر ورودی این متد یک نمونه از کلاس InquaryConfirm( جدول شماره 5 )می باشد.
مقدار بازگشتی از این متد یک نمونه از کلاس ConfirmResponse( جدول شماره 6 )می باشد.
در این مقاله در مورد متدهای وب سرویس درگاه بانک مسکن صحبت کردیم در مقاله بعد در مورد جداول راهنما API درگاه پرداخت مسکن توضیح میدهیم.