مستندات API درگاه پرداخت شاد

مقدمه

سرویس درگاه پرداخت شاد برای تسهیل خدمات پرداخت برای کاربرانی طراحی و پیاده‌سازی شده است که با اپلیکیشن شاد در تعامل هستند. این API با هدف ساده‌سازی فرآیندهای پرداخت و فراهم آوردن امکان ادغام آسان برای برنامه‌های خارجی توسعه داده شده است.

پیکربندی

کلید API (API Key)
هر ارائه‌دهنده سرویس یک کلید API منحصربه‌فرد از بخش فنی دریافت می‌کند.

شناسه رویداد (Event ID)
شناسه ی رویداد یک عدد منحصر به فرد است که برای رویداد مربوط به ارائه دهنده می باشد. از آنجا که هر ارائه دهنده ممکن است برای رویدادهای مختلف نیازمند پرداخت باشد از این شناسه برای دسته بندی پرداخت ها استفاده می شود.

متدهای وب سرویس

متد SendRequest

این متد برای ارسال درخواست پرداخت از طریق درگاه پرداخت شاد استفاده می‌شود.

آدرس:

https://shadpaymentgateway.shadnoyan.com/api/v1/Payment/SendRequest

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

پارامتر	نوع	اجباری	توضیحات
apiKey	string	بله	کلید API که باید در هدر درخواست ارسال شود.
eventId	int	بله	شناسه رویداد برای تراکنش پرداخت.
userId	string	بله	شناسه منحصربه‌فرد کاربر.
amount	int	بله	مبلغ پرداخت به ریال.
orderId	string	بله	شناسه منحصربه‌فرد سفارش.
additionalData	string	اختیاری	اطلاعات اضافی مربوط به تراکنش.
postCallBackUrl	string	بله	آدرس URL برای دریافت وضعیت تراکنش.
getRedirectUrl	string	بله	آدرس URL برای هدایت کاربر پس از تکمیل پرداخت.

نمونه درخواست:

curl -X 'POST' \
'https://shadpaymentgateway.shadnoyan.com/api/v1/Payment/SendRequest' \
-H 'accept: text/plain' \
-H 'apiKey: [Your apiKey]' \
-H 'Content-Type: application/json' \
-d '{
  "eventId": [Your EventId],
  "userId": [UserId],
  "amount": [Amount],
  "orderId": [OrderId],
  "additionalData": [AdditionalData],
  "postCallBackUrl": [PostCallBackUrl],
  "getRedirectUrl": [GetRedirectUrl]
}'

نمونه پاسخ:

{
  "isSuccess": true,
  "statusCode": 200,
  "code": 200,
  "data": "https link for redirect to bank payment page",
  "description": "با موفقیت انجام شد"
}

---

متد Reverse

این متد برای بازگرداندن تراکنش در مواردی استفاده می‌شود که کاربر پرداخت را با موفقیت انجام داده، اما امکان ارائه کالا یا خدمات وجود ندارد.

آدرس:

https://shadpaymentgateway.shadnoyan.com/api/v1/Payment/Reverse

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

پارامتر	نوع	اجباری	توضیحات
apiKey	string	بله	کلید API که باید در هدر درخواست ارسال شود.
orderId	string	بله	شناسه منحصربه‌فرد سفارش برای بازگشت وجه.

نمونه درخواست:

curl -X 'POST' \
'https://shadpaymentgateway.shadnoyan.com/api/v1/Payment/Reverse' \
-H 'accept: text/plain' \
-H 'apiKey: [Your apiKey]' \
-H 'Content-Type: application/json' \
-d '{
  "orderId": [OrderId]
}'

نمونه پاسخ:

{
  "isSuccess": true,
  "statusCode": 200,
  "code": 200,
  "description": "با موفقیت انجام شد"
}

نکات مهم

تنظیم amount: مقدار مبلغ برای ارسال به درگاه بانک باید بیشتر از ده هزار تومان معادل یکصدهزار ریال باشد.

تنظیم صحیح Event ID و API Key: اطمینان حاصل کنید که این دو پارامتر به درستی تنظیم شده‌اند تا تراکنش‌ها به موفقیت انجام شوند.
پیکربندی postCallBackUrl و getRedirectUrl: اطمینان حاصل کنید که این آدرس‌ها به درستی تنظیم شده‌اند تا وضعیت تراکنش دریافت و کاربر به آدرس صحیح هدایت شود.
تنظیم userId پارامتر user id یک رشته است، برای اینکه بتوان با کاربری که از شاد به رویداد هدایت شده ارتباط معنا دار برقرار کرد، این پارامتر باید مقدار user hash id ارائه شده از سوی شاد برای کاربر باشد.

مثال:

https://mysite.ir/shad?UserID=D4-76-29-46-BA-E1-88-74-C1-51-89-2A-D1-A8-58-C0

زمان درخواست بازگشت وجه: درخواست بازگشت وجه باید حداکثر تا 30 دقیقه پس از پرداخت موفق انجام شود.

اطلاعات اضافی

این API توسط شرکت فن‌آوری شبکه آموزش دانش‌نویان مدیریت می‌شود و برای ادغام با پلتفرم آموزشی شاد در نظر گرفته شده است. اطمینان حاصل کنید که از API به درستی استفاده شود تا یکپارچگی تراکنش‌ها حفظ و تجربه پرداختی یکپارچه برای کاربران فراهم شود.

نسخه: 2024، مهر ماه
منتشرکننده: شرکت فن‌آوری شبکه آموزش دانش‌نویان