آموزش اتصال به درگاه پرداخت با وب سرویس IDpay

امروزه اتصال یکپارچه و امن به درگاه پرداخت، یکی از ستون‌های اصلی هر کسب‌وکار آنلاین است. وب سرویس IDpay ابزاری قدرتمند در اختیار توسعه‌دهندگان قرار می‌دهد تا این فرآیند را به سادگی پیاده‌سازی کنند. اگر برنامه‌نویس هستید یا صاحب یک فروشگاه اینترنتی، این راهنما برای شماست.در این مقاله جامع (بخش اول)، به صورت گام به گام، شما را با مفاهیم اولیه و نحوه ایجاد اولین تراکنش از طریق وب سرویس IDpay آشنا می‌کنیم. بنابراین، با ما همراه باشید تا دروازه پرداخت آنلاین را به روی کسب‌وکار خود باز کنید. 🚀

وب سرویس IDpay چیست و چرا اهمیت دارد؟

وب سرویس آیدی پی در واقع یک رابط برنامه‌نویسی کاربردی (API) است. این رابط به شما اجازه می‌دهد تا وب‌سایت یا اپلیکیشن خود را مستقیماً به سیستم درگاه پرداخت IDpay متصل کنید. در نتیجه، می‌توانید فرآیندهای مالی مانند ایجاد تراکنش، استعلام وضعیت و… را به صورت خودکار مدیریت نمایید.

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

مزایای کلیدی استفاده از وب سرویس IDpay

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

✅ سرعت و سهولت در پیاده‌سازی: مستندات شفاف و معماری RESTful این API، فرآیند اتصال را بسیار ساده و سریع کرده است.
🧪 محیط آزمایشی (Sandbox): شما می‌توانید تمام فرآیندها را در یک محیط آزمایشی بدون ریسک و بدون انجام تراکنش واقعی تست کنید.
🎨 قابلیت شخصی‌سازی بالا: کنترل کامل بر فرآیند پرداخت به شما این امکان را می‌دهد که تجربه‌ای منحصر به فرد برای کاربران خود خلق کنید.
🔒 امنیت بالا: احراز هویت از طریق API Key و رعایت استانداردهای امنیتی، تراکنش‌های شما را کاملاً امن نگه می‌دارد.
📊 مستندات کامل و دقیق: آیدی پی مستندات جامعی را برای تمام نقاط پایانی (Endpoints) وب سرویس خود ارائه می‌دهد که کار را برای برنامه‌نویسان آسان می‌کند.

راهنمای گام به گام اتصال به وب سرویس IDpay (بخش اول)

اکنون زمان آن رسیده که وارد بخش عملی شویم. در این قسمت، مراحل اصلی برای شروع کار با وب سرویس IDpay، از دریافت کلید API تا ساخت اولین تراکنش را مرور می‌کنیم.

۱. پیش‌نیاز: دریافت کلید API (API KEY)

اولین قدم برای استفاده از هر API، احراز هویت است. وب سرویس آیدی پی از یک کلید منحصر به فرد به نام API KEY برای شناسایی شما استفاده می‌کند. برای دریافت این کلید:

ابتدا باید در پلتفرم آیدی پی یک حساب کاربری ایجاد کنید. اگر هنوز ثبت‌نام نکرده‌اید، می‌توانید از طریق لینک p.api.ir به سرعت این کار را انجام دهید.
سپس وارد داشبورد کاربری خود شوید.
به بخش «وب سرویس‌های من» بروید و یک وب سرویس جدید ایجاد کنید.
پس از ایجاد وب سرویس، API KEY اختصاصی شما نمایش داده می‌شود. این کلید را در جایی امن ذخیره کنید. 🔑

۲. احراز هویت: چگونه درخواست‌های خود را معتبر کنیم؟

برای تمام درخواست‌هایی که به سرورهای IDpay ارسال می‌کنید، باید API KEY خود را در هدر (Header) درخواست قرار دهید. این کار به سرور نشان می‌دهد که درخواست از طرف شما ارسال شده است. هدر مورد نیاز به شکل زیر است:

X-API-KEY: YOUR_UNIQUE_API_KEY

نکته مهم: حتماً عبارت YOUR_UNIQUE_API_KEY را با کلید واقعی که از داشبورد آیدی پی دریافت کرده‌اید، جایگزین کنید.

۳. محیط آزمایشی (Sandbox): تست بدون ریسک

یکی از بهترین ویژگی‌های وب سرویس IDpay، امکان تست در محیط Sandbox است. با فعال کردن این حالت، تمام تراکنش‌ها شبیه‌سازی می‌شوند و هیچ پولی جابجا نخواهد شد. برای فعال‌سازی، کافی است هدر زیر را به درخواست خود اضافه کنید:

X-SANDBOX: 1

با ارسال این هدر، محدودیت‌های مربوط به آدرس IP و دامنه callback نیز برداشته می‌شود تا بتوانید به راحتی از روی سیستم لوکال خود تست‌ها را انجام دهید.

۴. ایجاد اولین تراکنش: یک راهنمای عملی 💳

اصلی‌ترین کاربرد این وب سرویس، ایجاد یک تراکنش جدید است. برای این کار باید یک درخواست از نوع POST به آدرس زیر ارسال کنید:

آدرس درخواست (Endpoint):

POST https://api.idpay.ir/v1.1/payment

این درخواست باید شامل اطلاعات تراکنش در بدنه (Body) خود با فرمت JSON باشد. پارامترهای اصلی به شرح زیر هستند:

order_id: شماره سفارش منحصر به فرد شما (مثلاً شناسه‌ی فاکتور در سایت شما).
amount: مبلغ تراکنش به ریال.
callback: آدرس بازگشت کاربر پس از پرداخت. این آدرس باید با دامنه‌ای که در وب سرویس خود تعریف کرده‌اید، مطابقت داشته باشد.
name (اختیاری): نام پرداخت‌کننده.
phone (اختیاری): شماره موبایل پرداخت‌کننده.
mail (اختیاری): ایمیل پرداخت‌کننده.
desc (اختیاری): توضیحات تراکنش.

مثال بدنه درخواست (Request Body):

json

{
  "order_id": "101",
  "amount": 10000,
  "name": "نام کاربر",
  "phone": "09123456789",
  "mail": "user@example.com",
  "desc": "توضیحات مربوط به تراکنش",
  "callback": "https://example.com/callback"
}

پاسخ سرور در صورت موفقیت

اگر درخواست شما صحیح باشد، پاسخی با کد وضعیت 201 Created دریافت خواهید کرد. این پاسخ شامل دو مقدار کلیدی است که باید آن‌ها را در دیتابیس خود ذخیره کنید:

id: شناسه منحصر به فرد تراکنش در سیستم IDpay.
link: لینکی که باید کاربر را برای انجام پرداخت به آن هدایت کنید.

مثال پاسخ موفق (Status 201):

json

{
  "id": "d2e353189823079e1e4181772cff5292",
  "link": "https://idpay.ir/p/ws-sandbox/d2e353189823079e1e4181772cff5292"
}

پاسخ سرور در صورت خطا

در صورت بروز هرگونه خطا (مثلاً ارسال نکردن یک پارامتر ضروری)، پاسخی با کد وضعیت 4xx و یک پیام خطای مشخص دریافت می‌کنید.

مثال پاسخ خطا (Status 406):

json

{
  "error_code": 32,
  "error_message": "شماره سفارش `order_id` نباید خالی باشد."
}

کاربردهای وب سرویس درگاه پرداخت IDpay

این API قدرتمند در سناریوهای مختلفی قابل استفاده است. در اینجا به چند مورد از کاربردهای رایج آن اشاره می‌کنیم:

🛒 فروشگاه‌های اینترنتی: برای ایجاد یک فرآیند پرداخت سفارشی و یکپارچه با سیستم مدیریت موجودی.
🎓 پلتفرم‌های آموزشی: جهت فروش دوره‌های آنلاین و مدیریت پرداخت‌های دانشجویان.
✈️ سیستم‌های رزرواسیون: برای رزرو آنلاین هتل، بلیط هواپیما یا نوبت پزشک.
💰 اپلیکیشن‌های موبایل: برای پیاده‌سازی پرداخت درون‌برنامه‌ای در اپلیکیشن‌های اندروید و iOS.
❤️ موسسات خیریه: جهت دریافت کمک‌های مالی آنلاین به شکلی ساده و مستقیم.

جمع‌بندی و گام بعدی

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

در بخش دوم این سری مقالات، به موضوعات پیشرفته‌تری مانند استعلام وضعیت تراکنش و تایید نهایی پرداخت (Verify) خواهیم پرداخت که برای تکمیل چرخه پرداخت ضروری هستند.

🔗 گام بعدی: منتظر مقاله «وب سرویس IDpay بخش ۲: استعلام و تایید تراکنش» باشید!

آیا تجربه‌ای در استفاده از وب سرویس‌های پرداخت دارید؟ سوالات و نظرات خود را در بخش دیدگاه‌ها با ما به اشتراک بگذارید. ✍️