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

باکس دانلود :

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

دانلود مستند API درگاه

تعاریف

درگاه بانک: صفحه ای که کاربر با وارد کردن اطلاعات کارت بانکی خود ، میتواند عملیات پرداخت را انجام دهد.

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

IP های مجاز: IP هایی که مشتری سرویس رایان پی را توسط آنها فراخوانی میکند. این IP نباید تغییر کند و باید ثابت باشد.

کاربر: کاربر ، کسی است که قرار است پرداختی انجام داده و به صفحه بانک هدایت گردد.

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

درخواست توکن: دریافت شناسه یکتا که کاربر، با استفاده از آن به سایت بانک هدایت می شود.

درخواست پرداخت: یک درخواست جهت دریافت محتوایی به فرمت Html از رایان پی، تا با Post کردن این محتوا، کاربر بتواند به سایت بانک هدایت شود.

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

baseUrl : آدرس سرویس پرداخت رایان پی

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

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

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

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

همچنین آدرس baseUrl سرویس پرداخت رایان پی به شرح زیر است :

https://pms.rayanpay.com

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

تنها درخواست هایی پاسخ داده خواهند شد که از این لیست IP برای شرکت رایان پی ارسال شده باشد.

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

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

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

درخواست توکن

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

درخواست (Request)

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

پاسخ (Response)

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

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

مقدارتوضیحات
200موفق
400نقص در پارامترهای ارسالی
401کد کاربری/رمز عبور /کلاینت/آی پی نامعتبر است

 

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

درخواست (Request)

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

پاسخ (Response)

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

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

مقدارتوضیحات
401توکن نامعتبر
601اتصال به درگاه خطا دارد (پرداخت ناموفق)

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

Type: POST

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

درخواست (Request)

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

پاسخ (Response)

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

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

مقدارتوضیحات
401توکن نامعتبر است
200

پرداخت موفق

601پرداخت ناموفق
600پرداخت در حالت 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)

مقدارتوضیحات
200پرداخت موفق
401توکن نامعتبر است
600پرداخت در حالت Pending می باشد و باید متد fullfill برای تعیین وضعیت صدا زده شود
601 پرداخت ناموفق
602پرداخت یافت نشد
608قوانین پرداخت یافت نشد (برای پرداخت هایی که قوانین دارند)
609وضعیت پرداخت نامعتبر می باشد

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

لازم به ذکر است ، مشتری میتواند با مراجعه به آدرس ذیل جزییات بیشتری از سرویس ها را مشاهده نماید:

https://pms.rayanpay.com/swagger/index.html