وب‌سرویس‌های پی‌پینگ بر پایه REST پیاده‌سازی و بر اساس مشخصات OpenAPI مستند شده‌اند. در این راهنما با نحوه شروع کار با وب‌سرویس‌ها، روش‌های احراز هویت و کدهای وضعیت HTTP آشنا می‌شوید.
شروع کار با وب‌سرویس‌های پی‌پینگ
آدرس پایه تمام فراخوانی‌ها https://api.payping.ir است. برای مطالعه و تست متدها ابزارهای زیر در اختیار شماست:
- مستندات وب‌سرویس‌های پی‌پینگ: docs.payping.ir
- Swagger: آموزش استفاده از Swagger را در این صفحه ببینید.
- Postman: آموزش استفاده از Postman را در این صفحه ببینید.
توجه: فراخوانی وب‌سرویس‌ها تنها از سمت سرور امکان‌پذیر است. توکن و سایر اطلاعات احراز هویت را هرگز در سمت کاربر (فرانت‌اند) قرار ندهید.
احراز هویت
توکن اختصاصی (Bearer)
اگر وب‌سایت یا اپلیکیشن شخصی دارید و می‌خواهید از سرویس‌های مالی برای خودتان استفاده کنید، کافی است هدر Authorization را به‌صورت زیر روی درخواست‌هایتان تنظیم کنید:
Authorization: Bearer TOKEN
برای ساخت توکن اختصاصی به راهنمای ایجاد و ویرایش توکن مراجعه کنید. در زمان ساخت توکن، دسترسی‌های موردنیاز (مانند pay:read و pay:write) را مشخص می‌کنید؛ فقط دسترسی‌هایی را فعال کنید که واقعا به آن‌ها نیاز دارید.
توجه: اگر هنگام ساخت توکن، لیست آی‌پی‌های مجاز را تکمیل کرده‌اید، فراخوانی‌ها فقط از همین آی‌پی‌ها پذیرفته می‌شود و درخواست از آی‌پی‌های دیگر رد می‌شود.
OAuth2
استاندارد OAuth2 برای کسب‌وکارهایی کاربرد دارد که نیاز به دریافت دسترسی از کاربران پی‌پینگ دارند. با اتصال سرویس خود به پی‌پینگ می‌توانید کل فرآیند ثبت‌نام کاربرانتان را روی پی‌پینگ پیاده‌سازی کنید، احراز هویت آن‌ها را به ما بسپارید، برای آن‌ها پرداخت بسازید و از گزارش‌های پرداختشان در سرویس خود استفاده کنید.
برای آشنایی با این روش، راهنمای دریافت توکن اپلیکیشن OAuth2 را ببینید.
کدهای وضعیت HTTP
پس از ارسال هر درخواست، طبق قواعد وب‌سرویس‌های RESTful یک کد وضعیت به شما بازگردانده می‌شود. معنای هر کد در جدول زیر آمده است:
| کد | توضیح |
| 200 | عملیات با موفقیت انجام شد |
| 201 | درخواست با موفقیت ایجاد شد |
| 202 | درخواست پذیرفته شد اما عملیات هنوز در حال پردازش است؛ متد را مجددا فراخوانی کنید |
| 204 | عملیات با موفقیت انجام شد و پاسخی در بدنه وجود ندارد |
| 400 | مشکلی در داده‌های ارسالی درخواست وجود دارد |
| 401 | احراز هویت انجام نشده است؛ توکن نامعتبر است یا ارسال نشده است |
| 403 | دسترسی غیرمجاز؛ دسترسی لازم برای این عملیات را ندارید |
| 404 | آیتم درخواستی مورد نظر موجود نیست |
| 409 | تعارض وضعیت؛ برای مثال تراکنش قبلا تایید شده است |
| 500 | مشکلی در سرور رخ داده است |
| 502 | ارتباط با سرویس بالادستی برقرار نشد؛ عملیات در حال پردازش است و متد را مجددا فراخوانی کنید |
| 503 | سرور در حال حاضر قادر به پاسخگویی نیست |
گام بعدی
برای پیاده‌سازی پرداخت، از راهنماهای زیر شروع کنید:
- پرداخت ساده (درگاه پرداخت اینترنتی) — پیاده‌سازی کامل جریان پرداخت از ساخت تا تایید
- پرداخت تسهیمی — تقسیم خودکار مبلغ پرداخت بین چند ذی‌نفع
در صورت داشتن هرگونه سوال و نیاز به راهنمایی ، با پشتیبانی آنلاین سایت پی‌پینگ در ارتباط باشید.
به روز شده در: 1405/07/28