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

فهرست :

مستند پیش رو نحوه اتصال به درگاه پرداخت اینترنتی رایان پی را شرح می‌دهد، شامل رویه‌های مورد نیاز جهت پیاده‌سازی، سرویس‌ها و پارامترهای مورد نیاز. سرویس‌ها با دو پروتکل Soap و Rest پیاده سازی شده است.

باکس دانلود :

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

فهرست واژگان

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

نیازمندی‌های سامانه جهت پیاده سازی

  • کد درگاه پرداخت (Merchant Code): کد یکتا و 36 کاراکتری که رایان پی به هر پذیرنده اختصاص می‌دهد.
  • ادرس IP پذیرنده : آدرس سرور پذیرنده جهت صحت سنجی درخواست.

نحوه دسترسی

برای دسترسی به سامانه دو راه وجود دارد که می‌توانید از هر کدام بنا به ترجیح خود استفاده نمایید: 1. سرویس Soap 2. سرویس Rest

سرویس Soap

آدرس های مورد نیاز جهت دسترسی به سامانه :

آدرس WSDL سامانه : https://pms.rayanpay.com/pg/services/webgate/wsdl

آدرس ارجاع کاربران به درگاه پرداخت رایان پی پس از دریافت اعتبار سنجی : https://pms.rayanpay.com/pg/startpay/$Authority

جریان مورد نیاز جهت پیاده سازی پرداخت

1. سبد خرید

خریدار یا دارنده کارت با مراجعه به وب سایت پذیرنده و انتخاب كالا یا خدمات مورد نیاز، آماده پرداخت مبلغ فاكتور می‌شود.

2. ارسال اطلاعات به رایان پی

پذیرنده اطلاعات مورد نیاز درخواست پرداخت را با فراخوانی متد PaymentRequest به رایان پی ارسال می‌کند. در این زمان پذیرنده این متد PaymentRequest را فراخوانی می‌نماید.

پارامترهای ورودی متد PaymentRequest
نامنوعوضعیت پارامترتوضیحات
MerchantIdStringاجباریكد 36 كاراكتری اختصاصی پذیرنده
AmountIntegerاجباریمبلغ تراکنش به ریال
DescriptionStringغیراجباریاطلاعات اضافه تراکنش با فرمت Json(دقت گردد در صورتی که اطلاعات ارسالی با فرمت Json نباشد درخواست رد می شود)این فیلد نباید خالی ارسال شود.

نمونه :

 {“name”:”shahriar”,”lastname”:”pahlevansadgh”}

EmailStringغیراجباریآدرس ایمیل مشتری(با فرمت صحیح ایمیل ارسال گردد)
MobileStringغیراجباریشماره موبایل مشتری(با فرمت 98XXXXXXXXX)
CallbackURLStringاجباریادرس صفحه بازگشت مشتری پس از انجام تراکنش

PaymentRequest (

 ‘MerchantId’        => $MerchantId,

 ‘Amount’      => $Amount,

 ‘Description’        => $Description,

 ‘Email’               => $Email,

 ‘Mobile’              => $Mobile,

 ‘CallbackURL’    => $CallbackURL

);

پارامترهای خروجی متد PaymentRequest
نامنوعتوضیحات
StatusIntegerنتیجه درخواست(رجوع به جدول کدهای خطا)
AuthorityStringشناسه مرجع درخواست، درصورت موفق بودن دارای طول36 كاراكتر و در غیر اینصورت خالی میباشد.

نتیجه درخواست در صورت موفقیت آمیز بودن برابر 100 در غیر این صورت عددی منفی می‌باشد. پذیرنده موظف به نگهداری(ذخیره) شناسه Authority جهت استفاده در مراحل بعدی پرداخت است.

3. هدایت کاربر به صفحه درگاه پرداخت

در صورت موفقیت سرویس PaymentRequest پذیرنده می بایست خریدار را به درگاه پرداخت رایان پی Redirect کند. Authority دریافتی در انتهای آدرس درگاه رایان پی قرار می گیرد.

توضیحاتآدرس
نمونه لینک ارجاعhttps://pms.rayanpay.com/pg/startpay/$Authority

از زمان ارسال كاربر به درگاه رایان پی، مشتری حداکثر 15 دقیقه فرصت دارد كه عملیات پرداخت خود را انجام دهد، در غیر اینصورت Authority منقضی میشود.

4. بازگشت از صفحه درگاه پرداخت

بعد از پایان عملیات پرداخت، رایان پی كاربر را به سایت پذیرنده كه از طریق CallbackURL مشخص شده است باز می گرداند. رایان پی پارامترهای Authority و Status را به صورت QueryString به صفحه بازگشت مشتری (CallbackUrl) ارسال می‌کند. Status دارای دو مقدار ثابت “OK” و “NOK” است.

پرداخت ناموفق

درصورتی که این پارامتر دارای مقدار “NOK” باشد تراکنش ناموفق و نیازی به فراخوانی متد PaymentVerification نمی‌باشد و تراکنش در وضعیت نهایی ناموفق قرار دارد. پذیرنده تراکنش معادل را با استفاده از Authority ارسالی می تواند بازیابی کند.

پرداخت موفق

3. در صورت موفق بودن تراکنش(دریافت پاسخ “OK” در پارامتر Status) پذیرنده موظف است جهت تکمیل تراکنش متد PaymentVerification را فراخوانی نماید.

پارامترهای ورودی متد PaymentVerification
نامنوعوضعیت پارامترتوضیحات
MerchantIDStringاجباریكد 36 كاراكتری اختصاصی پذیرنده
AmountIntegerاجباریمبلغ تراکنش به ریال
AuthorityStringاجباریشناسه مرجع تراکنش

PaymentVerification(

 ‘MerchantID’         => $MerchantID,

 ‘Authority’          => $Authority,

 ‘Amount’      => $Amount

);

پارامترهای خروجی متد PaymentVerification
نامنوعتوضیحات
StatusIntegerنتیجه درخواست(رجوع به جدول کدهای خطا)
RefIDIntegerدر صورتی که تراکنش موفق باشد، شماره تراکنش پرداخت شده بازگشت داده می شود

نکته: پذیرنده تنها زمانی می تواند به مشتری سرویس خریداری شده را ارائه دهد که پاسخ متد PaymentVerification موفق باشد.

سرویس Rest

آدرس های مورد نیاز جهت دسترسی به سامانه :

توضیحاتآدرسمتد
سرویس درخواست پرداخت

https://pms.rayanpay.com/api/v2/ipg/paymentrequest

Post

آدرس ارجاع کاربران به درگاه پرداخت رایان پی پس از دریافت Authority

https://pms.rayanpay.com/pg/startpay/$Authority

GET

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

https://pms.rayanpay.com/api/v2/ipg/paymentVerification

Post

جریان مورد نیاز جهت پیاده سازی پرداخت

1.سبد خرید

خریدار یا دارنده کارت با مراجعه به وب سایت پذیرنده و انتخاب كالا یا خدمات مورد نیاز، آماده پرداخت مبلغ فاكتور می‌شود.

پذیرنده اطلاعات مورد نیاز پرداخت را به صورت  Json در body  ریکوئست درخواست پرداخت قرار داده و post می نماید.

Request Body:

{  “merchantID”: “string”,  “amount”: 0,  “description”: “string”,  “email”: “string”,  “mobile”: “string”,  “callbackURL”: “string” }

توضیحات: پارامتر های ورودی و خروجی در body دقیقا مشابه پارمترهای PaymentRequest در سرویس Soap می باشند.

2. بررسی فعال بودن مرچنت

پاسخ این سرویس همیشه Http Status Code=OK خواهد بود و داخل body اطلاعات زیر می باشد.

Response Body:

{  “status”: 0,  “authority”: “string” }

نتیجه درخواست (status) در صورت موفقیت آمیز بودن برابر 100 در غیر این صورت عددی منفی می‌باشد. پذیرنده موظف به نگهداری(ذخیره) شناسه Authority جهت استفاده در مراحل بعدی پرداخت است.

3. هدایت مشتری به درگاه پرداخت

در صورت موفقیت سرویس درخواست پرداخت ، پذیرنده می بایست خریدار را به درگاه پرداخت رایان پی Redirect کند. Authority دریافتی در انتهای آدرس درگاه رایان پی قرار می گیرد.

** زمان انقضای Authority  دقیقا مشابه سرویس Soap پانزده دقیقه می باشد.

4. بازگشت کاربر به سایت فروشگاه

بعد از پایان عملیات پرداخت، رایان پی كاربر را به سایت پذیرنده كه از طریق CallbackURL مشخص شده است باز می گرداند. رایان پی پارامترهای Authority و Status را به صورت QueryString به صفحه بازگشت مشتری (CallbackUrl) ارسال می کند. Status دارای دو مقدار ثابت “OK” و “NOK” است.

پرداخت ناموفق

درصورتی که این پارامتر دارای مقدار “NOK” باشد تراکنش ناموفق و نیازی به ارسال درخواست تایید پرداخت  نمی باشد و تراکنش در وضعیت نهایی ناموفق قرار دارد. پذیرنده تراکنش معادل را با استفاده از Authority ارسالی می تواند بازیابی کند.

پرداخت ناموفق

در صورت موفق بودن تراکنش(دریافت پاسخ “OK” در پارامتر Status) پذیرنده موظف است جهت تکمیل تراکنش، اطلاعات مورد نیاز را برای سرویس تایید پرداخت در body به صورت httppost ارسال نماید.

نکته: برای توضیح پارمترها به بخش Soap  مراجعه کنید.

Request Body:

{  “merchantID”: “string”,  “amount”: 0,  “authority”: “string” }

Response Body:

{  “status”:0,  “refId”:0 }

نکته: پذیرنده تنها زمانی می تواند به مشتری سرویس خریداری شده را ارائه دهد که پاسخ سرویس تایید پرداخت HttpStatusCode=Ok  و پارامتر status  موفق باشد.

متد دریافت مبلغ نهایی به همراه کارمزد سرویس پرداخت (دریافت کارمزد از مشتری / خریدار)

آدرس های مورد نیاز جهت دسترسی به سرویس:

آدرس
https://pms.rayanpay.com/api/v2/ipg/wageAddedAmount

نحوه استفاده از متد:

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

پارامترهای ورودی متد wageAddedAmount

نامنوعوضعیت پارامترتوضیحات
MerchantIDStringاجباریکد 36 کاراکتری اختصاصی پذیرنده
AmountDecimalاجباریمبلغ تراکنش به ریال

خروجی سرویس در صورت دریافت پاسخ 200 :

200 output response: {isSuccess(true/false),TotalAmount,errorMessage}

در صورتی که سرویس بتواند محاسبه را انجام بدهد فیلد isSuccess مقدار true خواهد داشت که در این‌صورت مبلغی که شامل کارمزد هم شده داخل totalAmount برگردانده می‌شود.
اگر سرویس در محاسبه به خطا بخورد، فیلد isSuccess مقدارش false خواهد بود و پیغام خطا در errorMessage نمایش داده خواهد شد

توجه کنید مبلغ totalAmount در واقع مبلغ نهایی هست که باید پرداخت شود و چون مبلغ کارمزد در آن لحاظ شده لذا کارمزد توسط مشتری پرداخت خواهد شد.

نیازمندی‌های امنیتی

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

جدول کد خطاها

کدتوضیحات
100عملیات با موفقیت انجام شده است

-1

اطلاعات ارسال شده ناقص است.

-2

IP یا Merchant Code پذیرنده صحیح نیست.

-3

با توجه به محدودیت های شاپرك امكان پرداخت با رقم درخواست شده میسر نمی باشد.

-11

درخواست مورد نظر یافت نشد.

-21

هیچ نوع عملیات مالی برای این تراكنش یافت نشد.

-22

تراكنش نا موفق می باشد.

-33

رقم تراكنش با رقم پرداخت شده مطابقت ندارد.

-40

اجازه دسترسی به متد مربوطه وجود ندارد.

-41

اطلاعات ارسال شده مربوط به AdditionalData غیرمعتبر میباشد.

-100

در انتظار پرداخت.

-101

آدرس بازگشت مشتری خالی است.

-102

در پرداخت خطایی رخ داده است.

-103

وضعیت پرداخت جهت تایید نادرست است.

-104

فروشگاهی با شناسه ارسالی یافت نشد.

-105

شناسه مرجع تراکنش اشتباه است

-106

خطای تایید پرداخت.

-107

وضعیت پرداخت صحیح نیست.

-109

فروشگاه غیر فعال است.

-110

شناسه ارسال شده نامعتبر است.

-111

پرداخت با شناسه ارسالی یافت نشد.

-112

فرمت توضیحات اشتباه است.

-113

فرمت موبایل اشتباه است.

 

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