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

فهرست :

• فهرست واژگان
• نیازمندی‌های سامانه جهت پیاده سازی
• سرویس Soap
• سرویس Rest
• پرداخت کارمزد
• نیازمندی‌های امنیتی
• جدول خطاها

مستند پیش رو نحوه اتصال به درگاه پرداخت اینترنتی رایان پی را شرح می‌دهد، شامل رویه‌های مورد نیاز جهت پیاده‌سازی، سرویس‌ها و پارامترهای مورد نیاز. سرویس‌ها با دو پروتکل 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

PaymentRequest (

 ‘MerchantId’        => $MerchantId,

 ‘Amount’      => $Amount,

 ‘Description’        => $Description,

 ‘Email’               => $Email,

 ‘Mobile’              => $Mobile,

 ‘CallbackURL’    => $CallbackURL

);

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

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

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

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

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

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

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

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

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

پرداخت موفق

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

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

PaymentVerification(

 ‘MerchantID’         => $MerchantID,

 ‘Authority’          => $Authority,

 ‘Amount’      => $Amount

);

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

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

سرویس Rest

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

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

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  موفق باشد.

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

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

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

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

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

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

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

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

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

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

جدول کد خطاها