مستندات پیادهسازی پذیرندگان سلف اسنپپی | راهنمای اتصال درگاه اختصاصی
این مستند با هدف ارائه وبسرویسهای مربوط به پیادهسازی ابزار پرداخت اقساطی دیجیپی نگاشته شده است. بهمنظور درک بهتر، تعاریف اساسی در ادامه بیان شده و در انتها فهرست کاملی از سرویسهای قابلارائه آورده شده است.
- دسترسی اولیهای که در اختیار شما قرار میگیرد، دسترسی محیط استیج (Stage) است. هدف از این دسترسی، پیادهسازی کامل سرویسها، تست سناریوها و اطمینان از صحت عملکرد اتصال شماست.
- پس از تایید پیادهسازی در جلسات فنی و دمو (pre-demo و demo)، دسترسی نهایی یعنی محیط پروداکشن (Production) در اختیار شما قرار خواهد گرفت و از آن لحظه امکان ارائه سرویس به کاربران واقعی فراهم میشود.
- در صورت مشاهده هرگونه استفاده نادرست، غیرمجاز یا سوءاستفاده از سطوح دسترسی، دسترسی شما بهصورت کامل قطع خواهد شد و پیگیری قانونی انجام میشود.
مقدمه
خرید اقساطی اسنپ یک راهکار پرداخت اعتباری است که توسط گروه اسنپپی فراهم شده تا امکان خرید با بازپرداخت اقساطی را در اختیار کاربران اسنپ که حساب اعتباری اسنپپی خود را فعال نمودهاند قرار دهد.
شما بهعنوان یک پذیرنده و ارائهدهنده خدمات میتوانید با فراهم نمودن این روش پرداخت برای کاربران خود، به آنها اجازه دهید بدون نیاز به پرداخت تمام مبلغ، خرید کنند. کاربر بسته به نوع روش پرداخت، در روش پرداخت اقساطی صرفاً مبلغی بهعنوان قسط اول پرداخت خواهد کرد و باقی بدهی خود را طی چند قسط در ماههای آتی پرداخت خواهد کرد. همچنین در روش پرداخت آخر ماه نیز، کل مبلغ سفارش در آخر ماه پرداخت خواهد شد.
این راهکار به دلیل افزایش قدرت خرید لحظهای کاربران، در افزایش نرخ فروش شما تاثیرگذار خواهد بود.
قالب کلی پاسخ درخواستها
در هر فراخوانی موفق API (کدهای وضعیت HTTP از نوع 2xx)، بدنه پاسخ بهصورت یک شیء JSON و در قالب نمونه کد سمت چپ ارائه میشود.
در فراخوانیهای ناموفق (کدهای وضعیت HTTP از نوع 4xx و 5xx) نیز بدنه پاسخ مطابق نمونه دوم در پنل کد بازگردانده خواهد شد.
مکانیزم امنسازی درخواستها
در فراخوانی هر یک از سرویسهای ارائهشده در این مستند، ضروری است درخواست ارسالی شامل یک توکن امنیتی از جنس JWT باشد که ایجاد آن از طریق فراخوانی API زیر میسر میشود.
برای فراخوانی هر سرویس، از جمله همین API، لازم است IP ماشین فراخوانیکننده از قبل توسط اسنپپی Whitelist شده باشد. درخواستهای با منبع ناشناخته پردازش نخواهند شد.
پس از دریافت توکن، باید آن را درون هدر Authorization تمامی درخواستهای بعدی خود قرار دهید. این توکن زمان اعتبار محدودی دارد (۳۶۰۰ ثانیه) و پس از پایان آن باید توکن جدید دریافت کنید.
توکن دسترسی (JWT) را کش نکنید و اجازه دهید بهدرستی منقضی شود؛ در غیر اینصورت ممکن است در ادامه فرآیند با خطای دسترسی مواجه شوید.
درخواست بررسی امکان پرداخت اقساطی (Eligible)
یک پذیرنده ممکن است روشهای متفاوتی برای تسویه حساب مالی پیادهسازی کند که یکی از آنها روش پرداخت اقساطی اسنپپی است. لازم است با فراخوانی این سرویس و بررسی نتیجه بازگشتی، نسبت به نمایش یا عدم نمایش گزینه پرداخت اقساطی تصمیم بگیرید.
این سرویس بهصورت داینامیک مبالغ اقساط را محاسبه میکند. با هر تغییر قیمت، لازم است مجدداً این سرویس فراخوانی شود؛ محاسبه مبالغ اقساط با هیچ روش دیگری قابلقبول نیست.
پارامترهای ورودی
| نام پارامتر | نوع | الزامی | مقادیر مجاز |
|---|---|---|---|
| amount | Query param | بله | مبلغ به ریال (IRR) |
| paymentMethodTypes | Query param (Array) | خیر | POSTPAID, INSTALLMENT, FINANCING |
ارسال پارامتر paymentMethodTypes اختیاری است و تنها زمانی باید ارسال شود که بخواهید کاربر را به استفاده از یک یا چند روش پرداخت مشخص محدود کنید. در صورت عدم ارسال یا ارسال آرایه خالی، کاربر تمامی روشهای فعال و در دسترس را مشاهده خواهد کرد.
روند کلی پرداخت اقساطی اسنپپی
روند پرداخت زمانی آغاز میشود که پذیرنده با دریافت یک توکن JWT، از آن در هدر تمامی درخواستهای آتی استفاده کند.
- فراخوانی سرویس eligibility و تصمیمگیری درباره نمایش یا عدم نمایش روش پرداخت اسنپ در سایت پذیرنده.
- در صورت
trueبودن پاسخ eligibility و انتخاب این روش توسط کاربر، درخواست دریافت Payment Token با پارامترهای متناسب با خرید ارسال میشود. - هدایت کاربر به آدرس دریافتشده در
paymentPageUrlبرای انجام پرداخت. - دریافت نتیجه تراکنش در آدرس بازگشت (
returnURL) بهصورت POST. - فراخوانی سرویس Verify در صورت موفق بودن نتیجه، برای نهاییسازی تراکنش.
- فراخوانی سرویس Settle پس از پاسخ موفق Verify، برای اتمام قطعی خرید.
نکات مهم: مقدار transactionId باید در سیستم پذیرنده یکتا و بین ۵ تا ۱۰ رقم باشد (برای ارقام بالای ۱۰، حتماً از یک حرف استفاده شود). هر تب باز شده از سبد خرید باید یک تراکنشآیدی جداگانه داشته باشد.
آدرس بازگشت (returnURL) ارسالی باید دقیقاً با آدرس پایهای که هنگام تعریف پذیرنده معرفی و whitelist شده مطابقت داشته باشد؛ در غیر اینصورت درخواست رد میشود.
پس از بازگشت کاربر، پذیرنده باید فقط یکبار سرویس Verify را فراخوانی کند (حتی اگر آدرس بازگشت چندینبار فراخوانی شده باشد). آخرین قدم برای نهاییسازی خرید موفق، فراخوانی سرویس Settle به ازای پاسخ موفق Verify است.
درخواست دریافت Payment Token
به ازای هر خرید باید از طریق این سرویس یک توکن پرداخت جداگانه درخواست شود و در عملیات بعدی از همین توکن استفاده گردد.
پارامترهای بدنه درخواست
| نام پارامتر | الزامی | توضیحات |
|---|---|---|
| amount | بله | مبلغ کل خرید (IRR) |
| discountAmount | بله | مبلغ تخفیف (IRR) |
| externalSourceAmount | بله | مبلغ پرداختی از منبع خارجی (IRR) |
| mobile | بله | شماره موبایل کاربر |
| returnURL | بله | آدرس بازگشت پس از پرداخت (باید POST باشد) |
| transactionId | بله | شناسه یکتای هر تراکنش |
| cartList | بله | آرایه سبدهای خرید |
| forcedPaymentMethodTypes | خیر | POSTPAID, INSTALLMENT, FINANCING |
استفاده از پارامتر forcedPaymentMethodTypes نیازمند فعالسازی از سمت تیم اسنپپی است. در صورت پیادهسازی پرداخت آخر ماه، ارسال این پارامتر الزامی است.
نحوه محاسبه totalAmount و amount
برای هر سبد خرید: [تعداد] × [مبلغ آیتم] + [هزینه ارسال در صورت عدم احتساب] + [مالیات در صورت عدم احتساب] = [مبلغ کل سبد]
برای کل سفارش: مجموع مبلغ کل تمام سبدها منهای مبلغ تخفیف و مبلغ منبع خارجی، برابر با مبلغ نهایی سفارش خواهد بود.
در صورتی که تنوع دستهبندی محصولات شما زیاد نیست، پارامتر commissionType را بهصورت پیشفرض عدد ۱۰۰ ارسال کنید.
درخواست Verify
پس از تکمیل مراحل پرداخت از سمت کاربر، وی به آدرس بازگشت بههمراه پارامترهای ذیل منتقل میشود. پذیرنده ملزم است در صورت دریافت نتیجه پرداخت موفق، ظرف مدت محدود سرویس Verify را برای نهاییکردن تراکنش فراخوانی کند.
عدم فراخوانی Verify منجر به بازگشت مبلغ کسرشده از حساب کاربر و تغییر وضعیت سفارش به reverted خواهد شد.
پارامترهای دریافتی در Callback (متد POST)
| نام پارامتر | مقادیر ممکن | توضیحات |
|---|---|---|
| transactionId | xxxxxx-xxxxx | شناسه یکتای ارسالی در سرویس دریافت توکن پرداخت |
| state | OK / FAILED | OK یعنی خرید موفق بوده و باید Verify فراخوانی شود؛ FAILED یعنی نیاز به فراخوانی Revert است |
| amount | عدد (IRR) | مبلغ تراکنش |
درخواست Settle
گام بعدی پس از فراخوانی موفق Verify برای اتمام روند یک خرید موفق، فراخوانی سرویس Settle است. فراخوانی این درخواست الزامی بوده و تمامی سفارشاتی که به مرحله Verify رسیدهاند، نیازمند فراخوانی Settle هستند.
پس از فراخوانی Settle، صرفاً با فراخوانی سرویس Cancel امکان لغو سفارش وجود خواهد داشت.
درخواست Revert
نیازی به پیادهسازی این قسمت وجود ندارد. در صورت نیاز به پیادهسازی، تیم پشتیبانی اسنپپی به شما اطلاع خواهد داد.
پس از بازگشت کاربر از مراحل پرداخت، در صورتیکه نتیجه اعلامشده موفق باشد اما امکان ارائه خدمات به مشتری وجود نداشته باشد (مثلاً اتمام موجودی انبار)، باید سرویس Revert فراخوانی شود تا مبلغ کسرشده به کاربر بازگردانده شود.
امکان انجام Revert برای تراکنشی که به وضعیت Settle رسیده باشد، وجود ندارد.
درخواست Get Payment Status
برای استعلام وضعیت یک درخواست پرداخت که با مشکل مواجه شده و جلوگیری از مغایرت، از این سرویس استفاده کنید.
لیست وضعیتهای ممکن
مدیریت درخواست Verify
- فراخوانی اولیه: سرویس Verify را برای سفارش فراخوانی کنید و یک مهلت زمانی (Timeout) ۳۰ ثانیهای برای دریافت پاسخ تنظیم نمایید.
- رسیدگی به Timeout: اگر طی ۳۰ ثانیه هیچ پاسخی دریافت نشد، سرویس Get Payment Status را فراخوانی کنید تا وضعیت نهایی پرداخت استعلام گرفته شود.
- تصمیمگیری بر اساس پاسخ: اگر وضعیت VERIFY بود، Settle را فراخوانی کنید؛ اگر PENDING بود، مجدداً Verify را فراخوانی کنید؛ در غیر اینصورت سفارش را ناموفق تلقی کنید.
مدیریت درخواست Settle
- فراخوانی اولیه: درخواست Settle را برای سفارش Verifyشده فراخوانی کنید.
- عدم دریافت پاسخ: اگر Settle پاسخ
falseبرگرداند یا پاسخی نداد، سرویس Get Payment Status را برای استعلام وضعیت نهایی فراخوانی کنید. - تصمیمگیری: اگر وضعیت VERIFY بود، مجدداً Settle را فراخوانی کنید؛ اگر SETTLE بود، تراکنش موفق و نهایی تلقی میشود.
درخواست Cancel
چنانچه پس از اتمام فرآیند خرید و قرارگرفتن تراکنش در وضعیت Settle نیاز به لغو آن باشد، میتوانید با فراخوانی این سرویس تراکنش را لغو کنید.
پیادهسازی این درخواست الزامی است. به دلیل برگشتناپذیر بودن این عملیات، پیش از ارسال درخواست، تاییدیهای از ادمین دریافت کنید.
درخواست Update
چنانچه پس از اتمام فرآیند خرید و قرارگرفتن تراکنش در وضعیت Settle نیاز به تغییر مبلغ یا آیتمهای سبد خرید باشد، این درخواست از طریق سرویس Update ارسال و پردازش میشود. مبلغ درخواست Update باید کمتر از مبلغ کل سفارش باشد.
اگر یک محصول کاملاً حذف میشود، لازم است از بین آیتمهای سبد خرید نیز حذف شود. به دلیل برگشتناپذیر بودن این عملیات، پیش از ارسال، تاییدیهای از ادمین دریافت کنید.
پیادهسازی درخواست Update برای فروشگاههای چندآیتمی الزامی است.
سوالات متداول
معمولاً این خطا به دلیل وایت نبودن IP ایجاد میشود. برای رفع آن لازم است IP صحیح را جهت Whitelist شدن به تیم اسنپپی ارسال کنید.
این خطا به دلیل نادرست بودن اطلاعات Authorization (انکد اشتباه Client ID و Client Secret) رخ میدهد. فرآیند انکد و مقادیر Username و Password را مطابق بخش مکانیزم امنسازی درخواستها بررسی کنید و از صحت متد و آدرس درخواست نیز اطمینان حاصل کنید.
برای تست API و جلوگیری از بروز خطا میتوانید از کالکشن Postman آمادهشده توسط اسنپپی استفاده کنید.
بله، برای زبانهای برنامهنویسی سمت بکاند از جمله PHP، .NET و... نمونه کدهای آماده در نظر گرفته شده است که در همین صفحه (پنل سمت چپ) قابل مشاهده است.
دقت کنید توکن دسترسی (JWT) زمان انقضای ۳۶۰۰ ثانیهای دارد. بنابراین توکن نباید کش شود تا در ادامه فرآیند با خطای دسترسی مواجه نشوید.
نحوه نمایش روش پرداخت اسنپپی از موارد بسیار مهمی است که باید دقیقاً پیادهسازی شود:
- در خط اول عنوان (title) و در خط بعدی توضیحات (description) نمایش داده شود؛ نحوه نمایش صحیح در نسخه موبایل نیز اهمیت زیادی دارد.
- سرویس eligible باید دقیقاً مطابق مستندات پیادهسازی شود. در صورت true بودن، عنوان و توضیحات بدون تغییر نمایش داده شود و در صورت false بودن، روش پرداخت نمایش داده نشود.
- از هرگونه پیادهسازی دستی خودداری کرده و حتماً سرویس eligible را بهدرستی پیادهسازی کنید.
- برای مبالغ پایین ۴ هزار تومان و بالای ۱۰ میلیون تومان (در محیط تست)، سرویس باید false برگرداند و روش پرداخت نمایش داده نشود.
- عنوان و توضیحات بازگشتی از eligible همیشه داینامیک هستند و نباید بهصورت ثابت از سمت پذیرنده نمایش داده شوند.
ابتدا برای پیادهسازی و تست، دسترسی محیط Stage در اختیار قرار میگیرد. پس از تایید پیادهسازی در جلسات pre-demo و دمو توسط کارشناسان فنی اسنپپی، دسترسی محیط Production ارسال خواهد شد.
بله، این درخواست برای فروشگاههای چندآیتمی الزامی بوده و نیازمند پیادهسازی است.
تاریخچه تغییرات مستند
| ویرایش | تاریخ | توضیحات |
|---|---|---|
| 1.0 | 2022-02-13 | ایجاد سند |
| 1.1 | 2022-03-05 | حذف پارامتر callback از روند خرید |
| 1.2 | 2022-04-16 | بروزرسانی APIهای get payment token و merchant eligibility |
| 1.3 | 2022-05-01 | بروزرسانی get payment token API (اجباریشدن cartList، totalAmount، cartItems) |
| 1.4 | 2022-05-08 | افزودن Get Payment Status API |
| 1.5 | 2022-05-14 | افزودن Cancel API |
| 1.6 | 2022-05-16 | افزودن Update API |
| 1.7 | 2022-09-20 | افزودن پارامترهای externalSourceAmount و commissionType |
| 1.8 | 2023-01-08 | بروزرسانی Get Payment Status (افزودن پارامتر amount) |
| 1.9 | 2024-09-01 | افزودن جزئیات به توضیحات هر API و افزودن بخش سوالات متداول |
| 2.0 | 2026-01-19 | افزودن بخش پیمنتلیست در سرویسهای get payment token و eligible |