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

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

باکس دانلود :

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

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

فهرست واژگان

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

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

  • کد درگاه پرداخت (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

نام

نوع

وضعیت پارامتر

توضیحات

MerchantID

String

اجباری

كد 36 كاراكتری اختصاصی پذیرنده

Amount

Integer

اجباری

مبلغ تراکنش به ریال

Description

String

غیراجباری

اطلاعات اضافه تراکنش با فرمت Json(دقت گردد در صورتی که اطلاعات ارسالی با فرمت Json نباشد درخواست رد می شود)

Email

String

غیراجباری

آدرس ایمیل مشتری(با فرمت صحیح ایمیل ارسال گردد)

Mobile

String

غیراجباری

شماره موبایل مشتری(با فرمت 98XXXXXXXXX)

CallbackURL

String

اجباری

ادرس صفحه بازگشت مشتری پس از انجام تراکنش

PaymentRequest (

 ‘MerchantID’        => $MerchantID,

 ‘Amount’      => $Amount,

 ‘Description’        => $Description,

 ‘Email’               => $Email,

 ‘Mobile’              => $Mobile,

 ‘CallbackURL’    => $CallbackURL

);

پارامترهای خروجی متد PaymentRequest

نام

نوع

توضیحات

Status

Integer

نتیجه درخواست(رجوع به جدول کدهای خطا)

Authority

String

شناسه مرجع درخواست، درصورت موفق بودن دارای طول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

نام

نوع

وضعیت پارامتر

توضیحات

MerchantID

String

اجباری

كد 36 كاراكتری اختصاصی پذیرنده

Amount

Integer

اجباری

مبلغ تراکنش به ریال

Authority

String

اجباری

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

 

PaymentVerification(

 ‘MerchantID’         => $MerchantID,

 ‘Authority’          => $Authority,

 ‘Amount’      => $Amount

);

 

پارامترهای خروجی متد PaymentVerification

نام

نوع

توضیحات

Status

Integer

نتیجه درخواست(رجوع به جدول کدهای خطا)

RefID

Integer

در صورتی که تراکنش موفق باشد، شماره تراکنش پرداخت شده بازگشت داده می شود

نکته: پذیرنده تنها زمانی می تواند به مشتری سرویس خریداری شده را ارائه دهد که پاسخ متد 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  موفق باشد.

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

 سایت رایان پی دارای گواهینامه های معتبر می باشد. جهت امنیت ارتباط درگاه پرداخت رایان پی و پذیرنده توصیه میگردد سایت پذیرنده نیر دارای گواهینامه معتبر(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

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

 

همکاری در فروش 😍