راهنمای 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 نباشد درخواست رد می شود) این فیلد نباید خالی ارسال شود. نمونه :  {“name”:”shahriar”,”lastname”:”pahlevansadgh”}
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  موفق باشد.

 

 

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

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

آدرس

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

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

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

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

نام	نوع	وضعیت پارامتر	توضیحات
MerchantID	String	اجباری	کد 36 کاراکتری اختصاصی پذیرنده
Amount	Decimal	اجباری	مبلغ تراکنش به ریال

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

در صورتی که سرویس بتواند محاسبه را انجام بدهد فیلد 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	فرمت موبایل اشتباه است.