راهنمای API درگاه پرداخت رایان پی

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

باکس دانلود :

شما عزیزان می توانید راهنمای استفاده از API درگاه پرداخت رایان پی را از لینک زیر بصورت PDF دانلود نمایید.

تعاریف

درگاه بانک: صفحه ای که کاربر با وارد کردن اطلاعات کارت بانکی خود ، میتواند عملیات پرداخت را انجام دهد.
مشتری: مشتری ، به کسی اطلاق میشود که سرویس پرداخت شرکت رایان پی را پیاده سازی نموده و کاربر را به سایت بانک هدایت می نماید.
IP های مجاز: IP هایی که مشتری سرویس رایان پی را توسط آنها فراخوانی میکند. این IP نباید تغییر کند و باید ثابت باشد.
کاربر: کاربر ، کسی است که قرار است پرداختی انجام داده و به صفحه بانک هدایت گردد.
CallBackUrl : آدرسی در سمت مشتری، جهت نمایش نتیجه عملیات پرداخت. این اطلاعات در فراخوانی متد “درخواست پرداخت” ، ارسال می شود و کاربر بعد از پرداخت، به این آدرس هدایت می گردد.
درخواست توکن: دریافت شناسه یکتا که کاربر، با استفاده از آن به سایت بانک هدایت می شود.
درخواست پرداخت: یک درخواست جهت دریافت محتوایی به فرمت Html از رایان پی، تا با Post کردن این محتوا، کاربر بتواند به سایت بانک هدایت شود.
تایید درخواست: بدین معنی است که عملیات تسویه پرداخت صورت گرفته و پول از حساب کاربر به حساب مقصد انتقال داده میشود.
baseUrl : آدرس سرویس پرداخت رایان پی
تعیین وضعیت درخواست: بدین معنی است که مشتری می تواند، وضعیت پرداخت را با استفاده از پارامتر های خواسته شده، از رایان پی، پیگیری نماید.

اطلاعات لازم برای استفاده از API

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

نام فیلدنوع فیلدتوضیحات
UserNameStringکد کاربری مشتری
PasswordStringرمز عبور مشتری
ClientIDGuidشناسه یکتا مشتری

همچنین آدرس baseUrl سرویس درگاه پرداخت رایان پی به شرح زیر است :
https://pms.rayanpay.com

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

فرایند انجام پرداخت

برای انجام پرداخت توسط API نیاز است فرایند زیر توسط کاربر انجام شود :

  •  ابتدا مشتری با فراخوانی متد “درخواست توکن” توکن لازم برای انجام عملیات پرداخت را دریافت می کند.
    نیاز است توکن دریافت شده از فراخوانی این متد، در تمامی درخواست های بعدی در Header درخواست با اسکیما Bearer ارسال می شود.
  • سپس مشتری با فراخوانی متد “درخواست پرداخت” ،کد Html لازم برای هدایت کاربر به بانک را دریافت می کند.
    کد Html دریافت شده باید در Browser نوشته شود ( html دریافت شده باید Post شود) تا کاربر به صفحه پرداخت بانک متنقل شود.
    بعد از انجام عملیات پرداخت توسط کاربر در درگاه بانک، آدرس CallBackURL مشتری توسط بانک فراخوانی می شود تا مشتری از نتیجه تراکنش مطلع شود. در این آدرس نیاز است نتیجه عملیات پرداخت توسط مشتری به کاربر نهایی نمایش داده می شود.
  • سپس مشتری با فراخوانی متد “تایید درخواست” انجام عملیات پرداخت را تایید می کند.
    درصورت عدم فراخوانی این متد پرداخت انجام شده بعد از ۱۵ دقیقه بازگشت داده می شود و مبلغ پرداخت شده به حساب کاربر بازگردانده می شود.
  • مشتری می تواند در تمامی مراحل پرداخت ، وضعیت درخواست پرداخت را پیگیری نماید که این کار توسط فراخوانی متد “تعیین وضعیت درخواست” صورت می پذیرد. وضعیت های پرداخت در جدول “وضعیت درخواست” شرح داده شده است.

درخواست توکن

Type : POST
Path : /api/v1/auth/token/generate

درخواست (Request)

نام فیلدنوع فیلدحداقل
طول
حداکثر طولاجباری/اختیاریتوضیحات
clientIdString  اجباری شناسه یکتا
مشتری
userNameString  اجباری کد کاربری
مشتری
passwordstring  اجباریرمز عبور مشتری

پاسخ (Response)

نام فیلدنوع فیلدتوضیحات
tokenStringتوکن پرداخت
errDescStringتوضیحات خطا

وضعیت درخواست (httpStatusCode)

مقدارتوضیحات
۲۰۰موفق
۴۰۰نقص در پارامترهای ارسالی
۴۰۱کد کاربری/رمز عبور /کلاینت/آی پی نامعتبر است

درخواست پرداخت

درخواست (Request)

نام فیلدنوع فیلدحداقل طولحداکثر طولاجباری/اختیاریتوضیحات
amountlong  اجباریمبلغ پرداخت
callbackUrlString  اجباریآدرس URL مشتری.
این آدرس بعد از انجام عملیات بانکی ،توسط درگاه بانک فراخوانی میشود تا مشتری از نتیجه پرداخت مطلع شود.
gatewayIdint  اجباریشناسه درگاه پرداخت این فیلد در حال حاضر مقدار ۱۰۰ میگیرد.
referenceIdlong  اجباریشناسه یکتا مشتری.
به ازای هر پرداخت این شناسه توسط مشتری ایجاد می شود و لازم است مقدار یکتایی داشته باشد.
msisdnstring(12)e  اختیاریشماره موبایل کاربر پرداخت کننده.
فرمت مجاز : 989XXXXXXXXX
gateSwitchingAllowedboolean  اجباریاین فیلد همراه مقدار False دارد

پاسخ (Response)

نام فیلدنوع فیلدتوضیحات
bankRedirectHtmlStringمحتوای صفحه درگاه بانک. این محتوا نیاز است در Browser نوشته شود.

وضعیت درخواست (httpStatusCode)

مقدارتوضیحات
۴۰۱توکن نامعتبر
۶۰۱اتصال به درگاه خطا دارد (پرداخت ناموفق) (در صورت بروز خطا، اطلاعات ارسالی مانند شماره مویایل، مبلغ، آدرس برگشتی و… بررسی شوند)

تعیین وضعیت درخواست

Type: POST
Path : /api/v1/ipg/payment/fulfill/paymentId/{paymentId}

درخواست (Request)

نام فیلدنوع فیلدحداقل
طول
حداکثر طولاجباری/اختیاریتوضیحات
paymentIdlong  اجباریاین شناسه در خواست ParsePaymentResponse توسط مشتری ساخته شده و در پارامتر ReferenceId ارسال
شده

پاسخ (Response)

نام فیلدنوع فیلدتوضیحات
referenceIDlongاین شناسه در خواست ParsePaymentResponse توسط مشتری ساخته شده و در پارامتر ReferenceId ارسال شده
hashedBankCardNumberstringشماره هش شده کارت.این فیلد فقط برای پرداخت های موفق مقدار دارد.

وضعیت درخواست (httpStatusCode)

مقدارتوضیحات
۴۰۱توکن نامعتبر است
۲۰۰پرداخت موفق
۶۰۱پرداخت ناموفق
۶۰۰پرداخت در حالت Pending می باشد و باید متد fullfill برای تعیین وضعیت صدا زده شود

تایید پرداخت

Type : POST
Path : /api/v1/ipg/payment/response/parse

درخواست (Request)

نام فیلدنوع فیلداجباری/اختیاریتوضیحات
referenceIdlongاجباریشناسه یکتا مشتری.
این فیلد در هر خواست توسط مشتری پر میشود و لازم است به ازای هر پرداخت مقدار یکتا داشته باشد
headerstringاجباریهدر ارسال شده توسط بانک
contentstringاجباریهدر ارسال شده توسط بانک

Formatted Header and Content:
Haeder and Content in Bank CallBack Request are key-value Parameteres so we have to parse it and
seperate them with ‘&’ sperated character

Example:
Header:
“Accept=text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8&Accept-Encoding=gzip, deflate&Accept-Language=en-GB,en-US;q=0.9,en;q=0.8&Cache-Control=maxage=0&Connection=Keep-Alive&Content-Length=332&Content-Type=application/x-www-formurlencoded&Host=appapi.dashtservice.com&MS-ASPNETCORE-TOKEN=77a5df0d-9106-4b6f-9c09-ff0224dbf814&Origin=null&Upgrade-Insecure-Requests=1&User-Agent=Mozilla/5.0 (Linux; Android 7.0; SAMSUNG SM-J730F Build/NRD90M) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/9.4
Chrome/67.0.3396.87 Mobile Safari/537.36&X-Original-For=127.0.0.1:60182&X-Original-Proto=http”

Content:
“Amount=19000&HashedCardNumber=QQQQQQQQAAAAAAAA12Sfdfd&MID=&RefNum=GmshtyjwKStnN62y7dHFjjXefrereBIN05ueExIi/qSYKz&ResNum=3&Rrn=
138000444474,13804043474&SecurePan=502229******6130&State=OK&Status=2&TerminalId=12121212&Token=aaaaaaaaaaaaaa8&TraceNo=22222,11111&Wage”=

پاسخ درخواست (Response)

نام فیلدنوع فیلدتوضیحات
httpStatusCodeintوضعیت
paymentIdlongشناسه پیگیری پرداخت
hashedBankCardNumberstringشماره هش شده کارتفقط در پرداخت موفق این فیلد مقدار دارد
endDateDateTimeتاریخ ثبت وضعیت پرداختفقط در وضعیت پرداخت موفق و نا موفق این فیلد مقدار دارد

وضعیت درخواست (httpStatusCode)

مقدارتوضیحات
۲۰۰پرداخت موفق
۴۰۱توکن نامعتبر است
۶۰۰پرداخت در حالت Pending می باشد و باید متد fullfill برای تعیین وضعیت صدا زده شود
۶۰۱ پرداخت ناموفق
۶۰۲پرداخت یافت نشد
۶۰۸قوانین پرداخت یافت نشد (برای پرداخت هایی که قوانین دارند)
۶۰۹وضعیت پرداخت نامعتبر می باشد

مشاهده جزئیات سرویس

لازم به ذکر است ، مشتری میتواند با مراجعه به آدرس ذیل جزییات بیشتری از سرویس های  api درگاه پرداخت را مشاهده نماید:
https://pms.rayanpay.com/swagger/index.html

پیمایش به بالا