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

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

باکس دانلود :

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

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

تعاریف

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

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

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

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

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

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

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

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

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

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

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

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

نام فیلد نوع فیلد توضیحات
UserName String کد کاربری مشتری
Password String رمز عبور مشتری
ClientID Guid شناسه یکتا مشتری

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

https://pms.rayanpay.com

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

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

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

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

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

درخواست توکن

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

درخواست (Request)

نام فیلد نوع فیلد حداقل
طول
حداکثر طول اجباری/اختیاری توضیحات
clientId String     اجباری  شناسه یکتا
مشتری
userName String     اجباری  کد کاربری
مشتری
password string     اجباری رمز عبور مشتری

پاسخ (Response)

نام فیلد نوع فیلد توضیحات
token String توکن پرداخت
errDesc String توضیحات خطا

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

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

 

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

درخواست (Request)

نام فیلد نوع فیلد حداقل طول حداکثر طول اجباری/اختیاری توضیحات
amount long     اجباری مبلغ پرداخت
callbackUrl String     اجباری آدرس URL مشتری.
این آدرس بعد از انجام عملیات بانکی ،توسط درگاه بانک فراخوانی میشود تا مشتری از نتیجه پرداخت مطلع شود.
gatewayId int     اجباری شناسه درگاه پرداخت این فیلد در حال حاضر مقدار 100 میگیرد.
referenceId long     اجباری شناسه یکتا مشتری.
به ازای هر پرداخت این شناسه توسط مشتری ایجاد می شود و لازم است مقدار یکتایی داشته باشد.
msisdn string(12)e     اختیاری شماره موبایل کاربر پرداخت کننده.
فرمت مجاز : 989XXXXXXXXX
gateSwitchingAllowed boolean     اجباری این فیلد همراه مقدار False دارد

پاسخ (Response)

نام فیلد نوع فیلد توضیحات
bankRedirectHtml String محتوای صفحه درگاه بانک. این محتوا نیاز است در 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وضعیت پرداخت نامعتبر می باشد

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

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

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