راهنمای API درگاه پرداخت رایان پی
با API امکان استفاده از درگاه پرداخت در تمام پلتفرم و زبانهای برنامه نویسی وجود دارد. با راهنمای زیر برای توسعه دهندگان به راحتی درگاه پرداخت در بستر وب، موبایل و سیستمعامل و … قابل پیاده سازی میباشد. در راهنمای زیر زبان برقراری ارتباط بین درگاه پرداخت اینترنتی و سرویس شما با کدهای خطاهای برگشتی قرار داده شده است.
باکس دانلود :
شما عزیزان می توانید راهنمای استفاده از API درگاه پرداخت رایان پی را از لینک زیر بصورت PDF دانلود نمایید.
تعاریف
درگاه بانک: صفحه ای که کاربر با وارد کردن اطلاعات کارت بانکی خود ، میتواند عملیات پرداخت را انجام دهد.
مشتری: مشتری ، به کسی اطلاق میشود که سرویس پرداخت شرکت رایان پی را پیاده سازی نموده و کاربر را به سایت بانک هدایت می نماید.
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 مشتری توسط بانک فراخوانی می شود تا مشتری از نتیجه تراکنش مطلع شود. در این آدرس نیاز است نتیجه عملیات پرداخت توسط مشتری به کاربر نهایی نمایش داده می شود. - سپس مشتری با فراخوانی متد “تایید درخواست” انجام عملیات پرداخت را تایید می کند.
درصورت عدم فراخوانی این متد پرداخت انجام شده بعد از ۱۵ دقیقه بازگشت داده می شود و مبلغ پرداخت شده به حساب کاربر بازگردانده می شود. - مشتری می تواند در تمامی مراحل پرداخت ، وضعیت درخواست پرداخت را پیگیری نماید که این کار توسط فراخوانی متد “تعیین وضعیت درخواست” صورت می پذیرد. وضعیت های پرداخت در جدول “وضعیت درخواست” شرح داده شده است.
درخواست توکن
Type : POST
Path : /api/v1/auth/token/generate
درخواست (Request)
نام فیلد | نوع فیلد | حداقل طول | حداکثر طول | اجباری/اختیاری | توضیحات |
---|---|---|---|---|---|
clientId | String | اجباری | شناسه یکتا مشتری | ||
userName | String | اجباری | کد کاربری مشتری | ||
password | string | اجباری | رمز عبور مشتری |
پاسخ (Response)
نام فیلد | نوع فیلد | توضیحات |
---|---|---|
token | String | توکن پرداخت |
errDesc | String | توضیحات خطا |
وضعیت درخواست (httpStatusCode)
مقدار | توضیحات |
---|---|
۲۰۰ | موفق |
۴۰۰ | نقص در پارامترهای ارسالی |
۴۰۱ | کد کاربری/رمز عبور /کلاینت/آی پی نامعتبر است |
درخواست پرداخت
درخواست (Request)
نام فیلد | نوع فیلد | حداقل طول | حداکثر طول | اجباری/اختیاری | توضیحات |
---|---|---|---|---|---|
amount | long | اجباری | مبلغ پرداخت | ||
callbackUrl | String | اجباری | آدرس URL مشتری. این آدرس بعد از انجام عملیات بانکی ،توسط درگاه بانک فراخوانی میشود تا مشتری از نتیجه پرداخت مطلع شود. | ||
gatewayId | int | اجباری | شناسه درگاه پرداخت این فیلد در حال حاضر مقدار ۱۰۰ میگیرد. | ||
referenceId | long | اجباری | شناسه یکتا مشتری. به ازای هر پرداخت این شناسه توسط مشتری ایجاد می شود و لازم است مقدار یکتایی داشته باشد. | ||
msisdn | string(12)e | اختیاری | شماره موبایل کاربر پرداخت کننده. فرمت مجاز : 989XXXXXXXXX | ||
gateSwitchingAllowed | boolean | اجباری | این فیلد همراه مقدار False دارد |
پاسخ (Response)
نام فیلد | نوع فیلد | توضیحات |
---|---|---|
bankRedirectHtml | String | محتوای صفحه درگاه بانک. این محتوا نیاز است در Browser نوشته شود. |
وضعیت درخواست (httpStatusCode)
مقدار | توضیحات |
---|---|
۴۰۱ | توکن نامعتبر |
۶۰۱ | اتصال به درگاه خطا دارد (پرداخت ناموفق) (در صورت بروز خطا، اطلاعات ارسالی مانند شماره مویایل، مبلغ، آدرس برگشتی و… بررسی شوند) |
تعیین وضعیت درخواست
Type: POST
Path : /api/v1/ipg/payment/fulfill/paymentId/{paymentId}
درخواست (Request)
نام فیلد | نوع فیلد | حداقل طول | حداکثر طول | اجباری/اختیاری | توضیحات |
---|---|---|---|---|---|
paymentId | long | اجباری | این شناسه در خواست ParsePaymentResponse توسط مشتری ساخته شده و در پارامتر ReferenceId ارسال شده |
پاسخ (Response)
نام فیلد | نوع فیلد | توضیحات |
---|---|---|
referenceID | long | این شناسه در خواست ParsePaymentResponse توسط مشتری ساخته شده و در پارامتر ReferenceId ارسال شده |
hashedBankCardNumber | string | شماره هش شده کارت.این فیلد فقط برای پرداخت های موفق مقدار دارد. |
وضعیت درخواست (httpStatusCode)
مقدار | توضیحات |
---|---|
۴۰۱ | توکن نامعتبر است |
۲۰۰ | پرداخت موفق |
۶۰۱ | پرداخت ناموفق |
۶۰۰ | پرداخت در حالت Pending می باشد و باید متد fullfill برای تعیین وضعیت صدا زده شود |
تایید پرداخت
Type : POST
Path : /api/v1/ipg/payment/response/parse
درخواست (Request)
نام فیلد | نوع فیلد | اجباری/اختیاری | توضیحات |
---|---|---|---|
referenceId | long | اجباری | شناسه یکتا مشتری. این فیلد در هر خواست توسط مشتری پر میشود و لازم است به ازای هر پرداخت مقدار یکتا داشته باشد |
header | string | اجباری | هدر ارسال شده توسط بانک |
content | string | اجباری | هدر ارسال شده توسط بانک |
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)
نام فیلد | نوع فیلد | توضیحات |
---|---|---|
httpStatusCode | int | وضعیت |
paymentId | long | شناسه پیگیری پرداخت |
hashedBankCardNumber | string | شماره هش شده کارتفقط در پرداخت موفق این فیلد مقدار دارد |
endDate | DateTime | تاریخ ثبت وضعیت پرداختفقط در وضعیت پرداخت موفق و نا موفق این فیلد مقدار دارد |
وضعیت درخواست (httpStatusCode)
مقدار | توضیحات |
---|---|
۲۰۰ | پرداخت موفق |
۴۰۱ | توکن نامعتبر است |
۶۰۰ | پرداخت در حالت Pending می باشد و باید متد fullfill برای تعیین وضعیت صدا زده شود |
۶۰۱ | پرداخت ناموفق |
۶۰۲ | پرداخت یافت نشد |
۶۰۸ | قوانین پرداخت یافت نشد (برای پرداخت هایی که قوانین دارند) |
۶۰۹ | وضعیت پرداخت نامعتبر می باشد |
مشاهده جزئیات سرویس
لازم به ذکر است ، مشتری میتواند با مراجعه به آدرس ذیل جزییات بیشتری از سرویس های api درگاه پرداخت را مشاهده نماید:
https://pms.rayanpay.com/swagger/index.html