خانه / اسکریپت های شرکت راناز / سامانه پرداخت آنلاین RaPayment / راهنمای اتصال به وبسرویس سامنه RaPayment
پرشیُن هاست

راهنمای اتصال به وبسرویس سامنه RaPayment

مستندات مربوط به نسخه های پایین تر از ورژن ۱٫۳٫۰٫۰ می باشد . ورژن ۱٫۳٫۰٫۰ دارای مستنداتی متفاوت هست .

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

مستندات فنی اتصال به اسکریپت پرداخت RaPayment
نسخه ۱ – تیر ماه ۱۳۹۴

نسخه PHP

َAPI

تاریخچه بازنگری


نویسنده نسخه تاریخ توضیحات
شرکت داده پرداز راناز ۱ ۲۲ تیر ۱۳۹۴ نسخه اولیه

مقدمه

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

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

 

هدف

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

 

 

 

 

توضیحات اولیه جهت اتصال

در تمامی متد ها جهت اتصال به سامانه راپی منت نیاز به آدرس مکان نصب سامانه می باشد . همچنین نیازمند نام پوشه مربوط به API اتصال نیز می باشد که به طور پیشفرض  Api می باشد .

برای مثال در صورتی که مکان نصب سامنه آدرس http://payment.ranaz.ir/online باشد و همچنین نام پوشه API را تغییر نداده باشید ؛ آدرس اتصال به صورت http://payment.ranaz.ir/online/Api خواهد بود .

 

تمامی متد های به دلیل عدم نیاز به سخت افزار خاص به صورت متد POST طراحی شده است و همچنین تمامی پلاگین ها و آموزش ها جهت عدم نیاز به تنظیمات سرور به صورت CURL طراحی شده است .

تمامی مقادیر برگشتی از سامانه جهت راحتی کاربران به صورت JSON می باشد .

در تمامی نمونه کد ها از فانکشن curl استفاده شده است که به شرح زیر می باشد .

 

 

متد دریافت لیست زبان های سامانه :

جهت اتصال برای دریافت لیست زبان های سامانه به آدرس اتصال فایل lang.php را اضافه کرده ( http://payment.ranaz.ir/online/Api/lang.php ) . سپس بدون ارسال مقادیری اتصال را به عمل آورده و مقادیر برگشتی به صورت دو آرایه می باشد که به شرح زیر می باشد :

  1. متغیر languages : در این متغیر لیست کامل زیان های سامانه به صورت Array ارسال می شود . در این آرایه از متغیر name جهت ارائه نام سیستمی و مورد نیاز در مراحل بعدی قرار دارد ، از متغیر flag جهت ارسال آدرس لوگو پرچم کشوری که با آن زیان صحبت می کنند استفاده شده است ؛ و از متغیر value جهت نمایش عنوان زبان به کاربر استفاده شده است .
  2. متغیر defult مفادیر این متغیر یک داده متنی می باشد که نام سیستمی و مورد نیاز زبان پیشفرض سامانه راپی منت در آن قرار دارد .

 

نمونه کد جهت دریافت لیست زبان ها :

خروجی آزمایشی کد فوق :

 

 

 

متد دریافت متغیرهای زبان انتخابی کاربر  :

جهت اتصال برای دریافت متغیر های زبان انتخابی به آدرس اتصال فایل getlang.php را اضافه کرده ( http://payment.ranaz.ir/online/Api/getlang.php ) . سپس نام سیستمی زبان مورد نظر را در متغیر language ذخیره کرده و با استفاده از آن اتصال را به عمل آورده و مقادیر برگشتی به صورت لیستی از آرایه ها می باشد که همراه با متغیر خود در صفحه شما جهت نمایش پیغام ها با زبان کاربر استفاده خواهد شد .

نمونه کد جهت دریافت لیست زبان ها :

 

 

 

متد دریافت لیست درگاه های فعال سامانه راپی منت و فیلد های اضافه  :

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

جهت اتصال برای دریافت متغیر های زبان انتخابی به آدرس اتصال فایل form.php را اضافه کرده ( http://payment.ranaz.ir/online/Api/form.php ) . سپس نام سیستمی زبان مورد نظر را در متغیر language ذخیره کرده و در صورتی که پرداخت برای یک سرویس خاص باشد که قبلا در مدیریت راپی منت ذخیره شده است ؛ ID سرویس مورد نظر را به صورت متغیر عددی در متغیر service_id ذخیره کرده . با استفاده از آن ها اتصال را به عمل آورده و مقادیر برگشتی به صورت لیستی از آرایه ها می باشد که به شرح زیر می باشد :

  1. آرایه portal : در این آرایه لیستی از درگاه های پرداخت به صورت آرایه های منظم برای شما ارسال می شود . در این آرایه متغیر name جهت نمایش نام درگاه متناسب با زبان انتخابی کاربر می باشد . متغیر file جهت ارسال های بعدی به راپی منت می باشد و نام سیستمی درگاه ها نمایش دهنده به کاربر می باشد .
  2. آرایه filds : در این آرایه لیستی کامل از فیلد های اضافی متناسب با سرویس مورد نظر و یا فیلد های عمومی را به صورت آرایه برای شما ارسال می کند . در این آرایه متغیر های متفاوتی بر حسب نوع فیلد ( کشویی ، متنی ، چک باکس و …. ) به صورت مقدار متنظر در اچ تی ام ال ( selectbox , text , checkbox , … ) برای شما ارسال می شود . که متغیر name جهت ارائه نام متغیر ذخیره کننده اطلاعات ان فیلد جهت ارسال به راپیمنت از طرف شما میباشد . متغیر discription جهت نمایش توضیحات آن فیلد به کاربر می باشد . متغیر required جهت الزام در وارد کردن اطلاعات به شما نمایش داده می شود . متغیر value مقدار پیشفرض فیلد را به کاربر نمایش می دهد و مقدار varchar نام فیلد را به کاربر نشان می دهد ( برای مثال ” شماره تلفن : ” ) .

نمونه کد جهت دریافت لیست زبان ها :

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

 

 

 

متد ارسال اطلاعات به بانک و دریافت کد پیگیری :

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

در این متد نیز در صورتی که سرویس خاصی مد نظر داشته باشید به ارسال ID سرویس ؛ سامانه راپی منت مقدار مبلغ و توضیحات خرید را خودکار از سرویس دریافت می کند وجایگزین مبلغ و توضیحات ارسال شما به راپی منت می کند .

همچنین در این متد شما می توانید مقادیر بسیار زیادی اطلاعات که به آن ها پس از برگشت از بانک نیاز دارید را ذخیره برای راپی منت ارسال کنید تا در کمال امنیت پس از بازگشت از بانک در زمان پیگیری نتیبجه پرداخت برای شما ارسال شود . این مقادیر می توانند مواردی شبیه نام کاربری کاربر یا مبلغ و یا زمان و یا هر مورد دیگر باشد که امنیتش مهم هست و در زمان برگشت از بانک به آنها نیاز دارید . جهت ارسال این گونه اطلاعات باید تمامی اطلاعات را در یک آرایه به نام return_filds برای سایت ارسال فرمایید . نام متغیر های آرایه return_filds آزاد هست و با هر نامی که اطلاعات را در این متغیر ذخیره کنید پس از بازگشت از بانک مقادیر با همان متغیر برای شما ارسال می شود . به عنوان نمونه :

 

 

جهت اتصال برای دریافت متغیر های زبان انتخابی به آدرس اتصال فایل send.php را اضافه کرده ( http://payment.ranaz.ir/online/Api/send.php ) . سپس نام سیستمی زبان مورد نظر را در متغیر language ذخیره کرده و در صورتی که پرداخت برای یک سرویس خاص باشد که قبلا در مدیریت راپی منت ذخیره شده است ؛ ID سرویس مورد نظر را به صورت متغیر عددی در متغیر service_id ذخیره کرده .

همچنین نام کاربر ( الزامی ) را در متغیر name و نام خانوادگی کاربر (الزامی ) را در متغیر Lname و ایمیل کاربر (الزامی ) را در متغیر email و شماره همراه کاربر(الزامی) را در متغیر phone ذخیره فرمایید .

مبلغ را به ریال در متغیر amount ذخیره کرده و توضیحات تراکنش را در Description قرار داده و نام سیستمی درگاه پرداخت مورد نظر را ر متغیر portal قرار داده و آدرس بازگشت از بانک را در متغیر callbackurl ذخیره فرمایید .

توجه نمایید : در صورتی که شما از service_id استفاده نمایید متغیر ها مبلغ و توضیحات در سامنه راپی منت با داده های سرویس یکسان می شوند .

در صورتی که در متد دریافت لیست فیلد ها ؛ فیلدی وجود داشت ؛ تمامی فیلد ها را به صورت آرایه در custemfid ذخیره فرمایید . ( در صورتی که شما تمامی فیلد ها را دقیقا با name دریافت شده از راپی منت در form قرار داده که متد آن post باشد ؛ در صفحه دریافت مقادیر از خط زیر استفاده نمایید . )

 

با استفاده از تمامی متغیر های فوق که همه الزامی می باشد اتصال را به عمل آورده و مقادیر برگشتی به صورت لیستی از آرایه ها می باشد که به شرح زیر است :

  1. متغیر do : این متغیر به صورت یک عدد هست ( ۰ و ۱ ) . در صورتی که ۰ باشد یعنی در اتصال خطایی به وجود آمده است و ۱ یعنی اطلاعات به بانک ارسال شده است و آماده انتقال کاربر به درگاه هستید .
  2. متعیر error : این متغیر یک رشته است که در صورت عدم موفقیت در اتصال به بانک برای شما ارسال می شود و شرحی از خطای روی داده شده است .
  3. متغیر trans_id1 : شماره پیگبری اول را نمایش می دهد .
  4. متغیر trans_id2 : شماره پیگیری دوم را نمایش می دهد .
  5. متغیر form : در صورتی که اتصال به بانک موفقیت آمیز باشد ؛ باید این متغیر به کاربر نمایش دهید . این متغیر یک فرم html هست که باید دکمه submit را به فرم اضافه کرده و به کاربر نمایش دهید .

 

نمونه کد کامل این صفحه :

 

 

متد پیگری تراکنش و بازگشت از بانک :

پس از بازگشت از بانک ؛ کاربر به سمت ادرس بازگشت هدایت می شود و به آدرس ارسالی توسط شما در متد قبلی یک رشته کد شده جهت پیگیری سیستمی تراکنش به صورت متد GET تحت عنوان RANAZ_payment_id برای شما ارسال می شود .

جهت اتصال برای دریافت متغیر های زبان انتخابی به آدرس اتصال فایل back.php را اضافه کرده ( http://payment.ranaz.ir/online/Api/back.php ) . سپس نام سیستمی زبان مورد نظر را در متغیر language ذخیره کرده و همچنین کد پیگیری سیستمی ( در متغیر RANAZ_payment_id  به صورت GET ارسال شده است ) را در متغییر id ذخیره فرموده  و اتصال را برقرار کرده  .

پاسخ سامانه راپی منت به درخواست شما به صورت کامل در یک آرایه ارسال می شود که لیست متغیر آرایه ها به شرح زیر می باشد :

  1. متغیر result : این متغیر یک عدد را برمی گرداند . در صورت برگشت عدد ۱ ؛ بدین معنی هست که تراکنش با موفقیت انجام شده است و شما هماکنون می توانید خدمات مورد نیاز را به کاربر ارائه دهید . در صورت برگشت عدد ۲ ؛ بدین معنی هست که تراکنش با موفقیت انجام شده است اما نتیجه با موفقیت قبلا برای شما ارسال شده است و کاربر دوباره اقدام به تایید تراکنش کرده است ( در این مورد نباید خدمتی ارائه داده شود . ) . در صورت برگشت عدد ۰ : بدین معنی است که تراکنش موفقیت آمیز نبوده است .
  2. متغیر error : در این متغیر متن خطای صورت کرفته ( در صورتی که متغیر result عداد ۲ و یا صفر را نمایش دهد ) را مطابق با زبان انتخابی کاربر برای شما ارسال می کند .
  3.  متغیر trans_id : شماره پیگیری اول را برای شما برمیگرداند .
  4. متغیر trans_id_2 : شماره پیگیری دوم را برای شما برمیگرداند .
  5. متغیر amount : مبلغ تراکنش را برای شما برمیگرداند .
  6. متغیر discription : توضیحات تراکنش را برای شما برمیگرداند .
  7. متغیر back_adress : لینک نمایش توضیحات پرداخت کاربر در سامانه راپی منت را  برمیگرداند .
  8. متغیر return_value : این متغیر به صورت یک آرایه می باشد که در ان لیستی از اطلاعات مورد نیاز شما ( اطلاعات ارسال شده در متد قبلی درون متغیر return_filds ) را برمیگرداند . نام متغیر های این آرایه همان نام هایی هست که در متد قبلی به یک داده خاص نسبت دادهاید .
  9. به غیر از موارد فوق حدود ده متغیر دیگر نیز ارسال می شود که مهم نمی باشد اما ممکن هست بعضی مواقع لازم شود که نام این متغیر ها با نام فیلد مورد نظر درون تیبل payment_log درون دیتابیس استفاده نمایید .

 

نمونه کد کامل این صفحه :

 

گزارشات

کاربران می توانند با ورود به بخش مدیریت سامانه راپی منت تمامی گزارشات پرداخت ها موفق و یا غیر موفق را مشاهده فرموده .

 

 

نمونه کد جهت ارائه در همین پست ضمیمه شده است .

ضمیمه های مطلب



جهت دانلود فایل های این مطلب روی این متن کلیک کنید.

منبع : صفر تا نه ( http://blog.0ta9.ir )

پرشیُن هاست

دیدگاه شما

( الزامي )

(الزامي)