فهرست :
- فهرست واژگان
- نیازمندیهای سامانه جهت پیاده سازی
- سرویس 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
نام | نوع | وضعیت پارامتر | توضیحات |
MerchantId | String | اجباری | كد 36 كاراكتری اختصاصی پذیرنده |
Amount | Integer | اجباری | مبلغ تراکنش به ریال |
Description | String | غیراجباری | اطلاعات اضافه تراکنش با فرمت Json(دقت گردد در صورتی که اطلاعات ارسالی با فرمت Json نباشد درخواست رد می شود)این فیلد نباید خالی ارسال شود. نمونه : {“name”:”shahriar”,”lastname”:”pahlevansadgh”} |
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 :
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 | فرمت موبایل اشتباه است. |