بسم الله الرحمن الرحیم

بخش دوم

برنامه نویسی درگاه پرداخت آنلاین

بخش اول (اتصال سایت به درگاه بانک)

بخش دوم (برنامه نویسی درگاه پرداخت آنلاین)

بخش سوم (آموزش راه اندازی درگاه بانک ملت)

بخش چهارم (برنامه نویسی درگاه بانک)

نوبت به طراحی و پیاده سازی درگاه پرداخت رسیده است.

برای شروع Visual Studio خود را باز نموده و یک پروژه از نوع Blank Solution ایجاد کنید. در اینجا ما نام پروژه را OnlinePayment انتخاب کرده ایم.

حال از قسمت Solution Explorer بر روی نام  Solution خود کلیک راست کنید و سپس گزینه Add -> New Project را انتخاب کنید.

در پنجره باز شده، یک پروژه از نوع وب سایت با نام Site به صورت زیر ایجاد کنید.

حال نوع پروژه را MVC انتخاب کنید و سپس از قسمت سمت راست بخشAuthentication  گزینه No Authentication را انتخاب کنید.

مجددا از قسمت Solution Explorer بر روی نام  Solution خود کلیک راست کنید و سپس گزینه Add -> New Project را انتخاب کنید.

در پنجره باز شده، یک پروژه از نوع Class Library با نام BankMellatLibrary به صورت زیر ایجاد کنید.

حال پروژه ما ایجاد شده است و می توانیم کار خود را شروع کنیم.

همانطور که تاکنون متوجه شدید ما دو پروژه را در Solution خود ایجاد کردیم. یک پروژه از نوع Class Library برای پیاده سازی وب سرویس های بانک ملت و یک پروژه از نوع ASP.NET MVC برای پیاده سازی یک وب سایت نمونه ایجاد کردیم.

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

1- bpPayRequest

2- bpVerifyRequest

3-  bpInquiryRequest

4- SettleRequest

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

 فرایند پرداخت توسط این 4 متد انجام می شود اگر این فرایند را توضیح دهیم می بایست به صورت زیر عمل کنیم.

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

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

وقتی کاربر عملیات خود را در صفحه بالا به پایان برساند؛ مجددا بانک ملت کاربر را به سایت ما هدایت می کند. همچنین بانک ملت اطلاعات را برای ما به صورت POST ارسال می کند.

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

حال باید برای حصول اطمینان از موفقیت آمیز بودن تراکنش از متد bpVerifyRequest بانک ملت استفاده کنیم، در صورتی که این متد نتیجه را مثبت اعلام کرد، فقط باید از بانک بخواهیم که تراکنش را پایان دهد و مبلغ مورد نظر را به حساب ما واریز کند،

اما در صورتی که این متد به هر شکلی جواب مثبت را ارئه نداد برای تست مجدد بهتر است از متد دیگر بانک ملت برای بررسی وضعیت نتیجه یک تراکنش استفاده کنیم؛ این متد bpInquiryRequest نام دارد.

در صورتی که همه چیز با موفقیت انجام شده باشد با استفاده از متد SettleRequest از بانک ملت می خواهیم تراکنش را با انتقال وجه به حساب ما به پایان برساند.

اضافه کردن وب سرویس بانک ملت

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

در گذشته وب سرویس تمامی بانک ها بر روی دامنه ی آنها قرار داشت اما با معرفی شبکه شاپرک تمام وب سرویس های بانک ها بر روی این شبکه فعالیت می کنند. متاسفانه تا امروز که در حال نوشتن این مقاله هستیم هنوز مستندات بانک ملت ویرایش نشده است! و آدرس درگاه پرداخت معرفی شده در مستندات بانک ملت اشتباه می باشد.

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

https://bpm.shaparak.ir/pgwchannel/services/pgw?wsdl

اضافه کردن وب سرویس بانک ملت به پروژه

برای اضافه کردن هر وب سرویسی به برنامه خود می بایست به صورت زیر عمل کنید:

در بخش Solution Explorer بر روی پروژه BankMellatLibrary خود کلیک راست کنید و سپس گزینه Add->  Service Reference را انتخاب کنید.

در پنجره Add Service Reference nv در پایین صفحه بر روی گزینه Advanced کلیک کنید مجددا در پنجره جدید باز شده در پایین صفحه بر روی گزینه Add Web Refrence کلیک کنید.

حال در پنجره باز شده در بخش URL، می بایست آدرس وب سرویس بانک ملت را وارد کنیم. آدرس زیر را در این بخش وارد کنید و سپس گزینه Go (ایکون فلش روبرو این TextBox) را انتخاب کنید.

https://bpm.shaparak.ir/pgwchannel/services/pgw?wsdl

حال اطلاعات وب سرویس بانک ملت برای شما می بایست نمایش داده شود.

در قسمت Web Refrence Name، بهتر است یک نام برای این وب سرویس تعیین کنید. ما MellatWebService را انتخاب می کنیم و سپس بر روی Add Refrence کلیک کنید.

اکنون اگر به قسمت Service References در پروژه BankMellatLibrary مراجعه کنید مشاهده خواهید کرد که وب سرویس بانک ملت در آنجا اضافه شده است.

برای پیاده سازی متدهای وب سرویس درگاه پرداخت بانک ملت یک کلاس در پروژه BankMellatLibrary با نام BankMellatImplement ایجاد کنید.

 معرفی وب سرویس به پرداخت ملت

متد bpPayRequest

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

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

این متد یک string به صورت زیر بر می گرداند، این مقدار بازگشتی دو بخش دارد

0 ,AF82041a2Bf6989c7fF9

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

بخش دوم، یک hashcode می باشد. این عدد (RefID (Refrence ID یا شماره پیگیری تراکنش شما است.

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

 اگر مقدار بازگشتی به غیر از 0 باشد یعنی خطایی اتفاق افتاده است و شما باید این خطا را مدیریت و بر طرف نمایید.

برای استفاده از این متد می بایست پارامترهای زیر را به این متد ارائه دهید.

1. در ﻫﺮ درﺧﻮاﺳﺖ ﭘﺬﻳﺮﻧﺪه، ﺑﺎﻳﺴﺘﻲ ﺷﻤﺎره درﺧﻮاﺳﺖ ﭘﺮداﺧﺖ ارﺳﺎﻟﻲ (orderId)، ﻳﻜﺘﺎ ﺑﺎﺷﺪ. در ﻏﻴـﺮ اﻳﻦ  ﺻﻮرت ﻣﻘﺪار ﺑﺎزﮔﺸﺘﻲ اﻳﻦﻣﺘﺪ ﺑﻮد ﭘﻴﻐﺎم ﺧﻄﺎ ﺧﻮاﻫﺪ.

به همین دلیل ما فیلد orderId را به صورت Auto number در SQL Server در نظر می گیریم تا مشکل تکراری بودن مقدار orderId ایجاد نشود.

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

بهتر است به جای IPدر تعیین آدرس callBackUrl ﺣﺘﻲ اﻻﻣﻜﺎن از Domain اﺳﺘﻔﺎده ﺷﻮد.

3. RefId ایی که توسط متد bpPayRequest درﻳﺎﻓﺖ می شود را باید به همان صورت به متد بعدی که معرفی خواهیم کرد انتقال دهید. زیرا RefId ﺣﺴﺎس ﺑﻪ ﻛﺎراﻛﺘﺮ (Case Sensitive) اﺳﺖ.

4. شناسه پرداخت کنند یا payerId در زمان کار با سرویس تست باید 0 باشد اما در زمان استفاده از سرویس اصلی باید با شناسه اصلی که بانک در اختیار شما قرار می دهد، مقدار دهی شود.

زﻣـــﺎن Session Timeout سایت می ﺑﺎﻳﺴﺖ ﺣﺪاﻗﻞ 15 دﻗﻴﻘﻪ باشد، ﺗﺎ اگر ﭘﻴﺶ از ﭘﺎﻳﺎن ﻳـﺎﻓﺘﻦ اﻳـﻦ زﻣـــﺎن خرید کاربر ﺑـــﻪ ﭘﺎﻳـــﺎن ﻧﺮﺳید ﻋﻤﻠﻴـــﺎت ﺑـــﺎ ﻣﺸـــﻜﻞ ﻣﻮاﺟـــﻪ نشود. در برخی از سرور ها، Firewall ﻣـــﺪﻳﺮﻳﺖ Session Timeout را ﺑﺮﻋﻬﺪه دارد، در این سرور ها باید تظیمات مربوط به Session Timeout در  Firewallنیز صورت گیرد.

حال می خواهیم اولین متد را پیاده سازی کنیم به درون کلاس BankMellatImplement که در مرحله آخر ایجاد کرده ایم می رویم.

چند پارامتر وجود دارد که در کل برنامه ثابت خواهد بود و تمامی متدها به این پارامترها نیاز دارند، این پارامترها را می توان در Setting پروژه یا Web.Config ذخیره نمود. در این برنامه ما این اطلاعات را در کلاس BankMellatImplement ذخیره می کنیم.

کلاس BankMellatImplement را که در مرحله قبل ایجاد کردیم، باز کنید سپس کدهای زیر را به این کلاس اضافه کنید، تا کد این کلاس به صورت زیر شود

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace BankMellatLibrary
{
    public class BankMellatImplement
    {

        #region Base Variable Definition

        public static readonly string PgwSite = "https://bpm.shaparak.ir/pgwchannel/startpay.mellat";
        static readonly string callBackUrl = "http://www.Ably.ir/Payment/BankCallback";
        static readonly long terminalId = long.Parse("111111");
        static readonly string userName = "ABLY.IR";
        static readonly string password = "111111";

        string localDate = string.Empty;
        string localTime = string.Empty;
        #endregion

        public BankMellatImplement()
        {
            try
            {
                localDate = DateTime.Now.ToString("yyyyMMdd");
                localTime = DateTime.Now.ToString("HHMMSS");
            }
            catch (Exception error)
            {
                throw new Exception(error.Message);
            }
        }

      }
}

متغییر PgwSite آدرس درگاه پرداخت بانک ملت بر روی شبکه شاپرک می باشد.

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

سه متغییر terminalId، username، password می بایست توسط شما با استفاده از اطلاعاتی که بانک ملت در اختیار شما قرار می دهد تکمیل شود.

localDate و localTime تاریخ و ساعت جاری کاربر می باشد که می بایست این دو پارامتر را به درگاه پرداخت ارسال کنیم. برای اینکه این دو متغییر همیشه مقدار دهی شده باشند آنها را در متد سازنده (Constructor) کلاس مقدار دهی می کنیم.

 متد BankMellatImplement، متد سازنده کلاس (Constructor) می باشد، این متد در زمان ساخته شدن یک شی از روی کلاس ما به صورت خودکار اجرا خواهد شد و متغییرهای localDate و localTime را با تاریخ و ساعت جاری سرور پر خواهد کرد.

نکته ی دیگری که وجود دارد وب سرویس بانک ملت تاریخ و ساعت را با یک قالب خاص نیاز دارد.

قالب تاریخ باید به صورت YYYYMMDD باشد که نتیجه آن بدین شکل خواهد بود: 20091008

قالب ساعت نیز باید به صورت HHMMSS باشد که نتیجه آن بدین شکل خواهد بود: 102003

در نتیجه ما باید تاریخ و ساعت را به صورت زیر در متغییر ها ذخیره کنیم.

 متغییرهای اصلی مورد نیاز را ایجاد کردیم، حال متد bpPayReques را به صورت زیر به کلاس خود اضافه می کنیم. نام این متد را bpPayReques می گذاریم.

متد ما به صورت زیر خواهد بود:

public string bpPayRequest(long orderId, long priceAmount, string additionalText)
{
    try
    {
      MellatWebService.PaymentGatewayImplService WebService = new MellatWebService.PaymentGatewayImplService();
      return WebService.bpPayRequest(terminalId, userName, password, orderId, priceAmount, localDate, localTime,
                       additionalText, callBackUrl, 0);

     }
     catch (Exception error)
     {
       throw new Exception(error.Message); ;
     }
}

توضیح کد:

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

پارامترهای localDate, localTime , terminalId, userName, password , callBackUrl را قبلا در بدنه کلاس خود مقداردهی کرده ایم و در اینجا تنها کافی است متغییرهای مربوطه را به متد bpPayReques معرفی کنیم.

علاوه بر پارامترهای بالا باید orderId, priceAmount و additionalText را به متد bpPayReques انتقال دهیم، این سه پارامتر به ازای هر خرید متفاوت خواهد بود. به همین دلیل این سه پارامتر را از ورودی متد SendRequest دریافت خواهیم کرد.

در نهایت آخرین پارامتر payerId خواهد بود که ما مقدار آن را 0 قرار می دهیم. این مقدار ثابت است.

همانطور که قبلا نیز ذکر کردیم، این متد یک string به صورت زیر بر می گرداند، این مقدار بازگشتی دو بخش دارد

0 ,AF82041a2Bf6989c7fF9

بخش اول که ResCode نامیده می شود یک عدد می باشد که وضعیت تراکنش شما را مشخص می کند، عدد دوم شماره و یا همان ID تراکنش می باشد.

ResCode می تواند شامل مقادیر زیادی باشد این مقادیر هر یک معانی خاصی خواهند داشت.

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

برخی از خطاهای زیر مربوط به برنامه نویس می باشد (مثلا اشتباه بودن نام کاربری و کلمه عبور) و برخی مربوط به مشتری می باشد (مثلا نداشتن مبلغ کافی در حساب).

نتایج بازگشتی درگاه پرداخت بانک ملت

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

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

 public enum MellatBankReturnCode
        {
            ﺗﺮاﻛﻨﺶ_ﺑﺎ_ﻣﻮﻓﻘﻴﺖ_اﻧﺠﺎم_ﺷﺪ = 0,
            ﺷﻤﺎره_ﻛﺎرت_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 11,
            ﻣﻮﺟﻮدی_ﻛﺎﻓﻲ_ﻧﻴﺴﺖ = 12,
            رﻣﺰ_ﻧﺎدرﺳﺖ_اﺳﺖ = 13,
            ﺗﻌﺪاد_دﻓﻌﺎت_وارد_ﻛﺮدن_رﻣﺰ_ﺑﻴﺶ_از_ﺣﺪ_ﻣﺠﺎز_اﺳﺖ = 14,
            ﻛﺎرت_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 15,
            دﻓﻌﺎت_ﺑﺮداﺷﺖ_وﺟﻪ_ﺑﻴﺶ_از_ﺣﺪ_ﻣﺠﺎز_اﺳﺖ = 16,
            ﻛﺎرﺑﺮ_از_اﻧﺠﺎم_ﺗﺮاﻛﻨﺶ_ﻣﻨﺼﺮف_ﺷﺪه_اﺳﺖ = 17,
            ﺗﺎرﻳﺦ_اﻧﻘﻀﺎی_ﻛﺎرت_ﮔﺬﺷﺘﻪ_اﺳﺖ = 18,
            ﻣﺒﻠﻎ_ﺑﺮداﺷﺖ_وﺟﻪ_ﺑﻴﺶ_از_ﺣﺪ_ﻣﺠﺎز_اﺳﺖ = 19,


            ﺻﺎدر_ﻛﻨﻨﺪه_ﻛﺎرت_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 111,
            ﺧﻄﺎی_ﺳﻮﻳﻴﭻ_ﺻﺎدر_ﻛﻨﻨﺪه_ﻛﺎرت = 112,
            ﭘﺎﺳﺨﻲ_از_ﺻﺎدر_ﻛﻨﻨﺪه_ﻛﺎرت_درﻳﺎﻓﺖ_ﻧﺸﺪ = 113,
            دارﻧﺪه_ﻛﺎرت_ﻣﺠﺎز_ﺑﻪ_اﻧﺠﺎم_اﻳﻦ_ﺗﺮاﻛﻨﺶ_ﻧﻴﺴﺖ = 114,


            ﭘﺬﻳﺮﻧﺪه_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 21,
            ﺧﻄﺎی_اﻣﻨﻴﺘﻲ_رخ_داده_اﺳﺖ = 23,
            اﻃﻼﻋﺎت_ﻛﺎرﺑﺮی_ﭘﺬﻳﺮﻧﺪه_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 24,
            ﻣﺒﻠﻎ_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 25,
            ﭘﺎﺳﺦ_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 31,
            ﻓﺮﻣﺖ_اﻃﻼﻋﺎت_وارد_ﺷﺪه_ﺻﺤﻴﺢ_ﻧﻤﻲ_ﺑﺎﺷﺪ = 32,
            ﺣﺴﺎب_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 33,
            ﺧﻄﺎی_ﺳﻴﺴﺘﻤﻲ = 34,
            ﺗﺎرﻳﺦ_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 35,
            ﺷﻤﺎره_درﺧﻮاﺳﺖ_ﺗﻜﺮاری_اﺳﺖ = 41,
            ﺗﺮاﻛﻨﺶ_Sale_یافت_نشد_ = 42,
            ﻗﺒﻼ_Verify_درﺧﻮاﺳﺖ_داده_ﺷﺪه_اﺳﺖ = 43,
            درخواست_verify_یافت_نشد = 44,
            ﺗﺮاﻛﻨﺶ_Settle_ﺷﺪه_اﺳﺖ = 45,
            ﺗﺮاﻛﻨﺶ_Settle_نشده_اﺳﺖ = 46,
            ﺗﺮاﻛﻨﺶ_Settle_یافت_نشد = 47,
            تراکنش_Reverse_شده_است = 48,
            تراکنش_Refund_یافت_نشد = 49,


            شناسه_قبض_نادرست_است = 412,
            ﺷﻨﺎﺳﻪ_ﭘﺮداﺧﺖ_ﻧﺎدرﺳﺖ_اﺳﺖ = 413,
            سازﻣﺎن_ﺻﺎدر_ﻛﻨﻨﺪه_ﻗﺒﺾ_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 414,
            زﻣﺎن_ﺟﻠﺴﻪ_ﻛﺎری_ﺑﻪ_ﭘﺎﻳﺎن_رسیده_است = 415,
            ﺧﻄﺎ_در_ﺛﺒﺖ_اﻃﻼﻋﺎت = 416,
            ﺷﻨﺎﺳﻪ_ﭘﺮداﺧﺖ_ﻛﻨﻨﺪه_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 417,
            اﺷﻜﺎل_در_ﺗﻌﺮﻳﻒ_اﻃﻼﻋﺎت_ﻣﺸﺘﺮی = 418,
            ﺗﻌﺪاد_دﻓﻌﺎت_ورود_اﻃﻼﻋﺎت_از_ﺣﺪ_ﻣﺠﺎز_ﮔﺬﺷﺘﻪ_اﺳﺖ = 419,
            IP_نامعتبر_است = 421,

            ﺗﺮاﻛﻨﺶ_ﺗﻜﺮاری_اﺳﺖ = 51,
            ﺗﺮاﻛﻨﺶ_ﻣﺮﺟﻊ_ﻣﻮﺟﻮد_ﻧﻴﺴﺖ = 54,
            ﺗﺮاﻛﻨﺶ_ﻧﺎﻣﻌﺘﺒﺮ_اﺳﺖ = 55,
            ﺧﻄﺎ_در_واریز = 61
        }

 این فرایند را در بخش بعد تکمیل خواهیم کرد.