مستندات اتصال درگاه پرداخت

مقدمه

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

پیش‌نیازها

برای اتصال، به کلیدهای اتصال فروشگاه خود نیاز دارید که در پنل فروشگاه، بخش «کلیدهای اتصال» در دسترس است. این کلیدها محرمانه‌اند و باید فقط در سمت سرور فروشگاه شما نگهداری شوند؛ هرگز آن‌ها را در سمت کاربر (مرورگر) قرار ندهید. همچنین باید در پنل فروشگاه «آدرس وب‌سایت» خود را ثبت کنید؛ این آدرس باید با https (دارای گواهی SSL معتبر) باشد و پس از تأیید نماد اعتماد الکترونیکی توسط اعتباریت، درگاه فعال می‌شود. درگاه فقط روی همان دامنهٔ ثبت‌شده کار می‌کند.

گام ۱: ایجاد پرداخت

با این فراخوانی یک سفارش باز می‌شود و توکن پرداخت به‌همراه آدرسی که باید کاربر را به آن هدایت کنید بازگردانده می‌شود. سفارش تا ۱۵ دقیقه معتبر است.

{
  "api_key": "etb_1a2b3c4d5e6f7g8h",
  "api_secret": "xxxxxxxxxxxxxxxxxxxx",
  "amount": 2500000,
  "callback_url": "https://your-shop.ir/etebarit/callback",
  "order_id": "A-1024"
}

{
  "success": true,
  "status": 100,
  "token": "8f2a...e7b1",
  "order_id": "ORD-40027153",
  "merchant_order_id": "A-1024",
  "amount": 2500000,
  "expires_at": "2026-07-25T12:00:00+00:00",
  "payment_url": ".../pay/8f2a...e7b1"
}

گام ۲: هدایت کاربر به درگاه

پس از دریافت پاسخ موفق، کاربر را به مقدار payment_url هدایت کنید. کاربر در صفحهٔ اعتباریت هویت خود را با پیامک تأیید کرده و پرداخت را (اقساطی، از کیف پول یا آنلاین) کامل می‌کند.

گام ۳: بازگشت به فروشگاه

پس از پایان پرداخت، کاربر به آدرس Callback شما بازگردانده می‌شود و پارامترهای زیر به‌صورت query string اضافه می‌شوند. توجه کنید که این بازگشت به‌تنهایی سند پرداخت نیست؛ همیشه باید نتیجه را در گام بعد با «تأیید پرداخت» بررسی کنید.

گام ۴: تأیید پرداخت

با ارسال توکن، پرداخت را قطعی کنید. نخستین فراخوانی موفق کد ۱۰۰ و فراخوانی‌های تکراری کد ۱۰۱ را با همان reference_id بازمی‌گردانند؛ بنابراین اگر تأیید را دوباره فراخوانی کنید، سفارش دوبار تحویل داده نمی‌شود. اگر amount را بفرستید، باید دقیقاً با مبلغ سفارش برابر باشد.

{
  "success": true,
  "status": 100,
  "order_id": "ORD-40027153",
  "merchant_order_id": "A-1024",
  "amount": 2500000,
  "reference_id": "483920157604",
  "paid_at": "2026-07-25T12:03:00+00:00"
}

کدهای وضعیت

همهٔ پاسخ‌ها با HTTP 200 و یک فیلد status بازمی‌گردند. کدهای مثبت موفقیت و کدهای منفی خطا هستند. فیلد success نیز درست یا نادرست بودن نتیجه را نشان می‌دهد.

نکات مهم

• کلید محرمانه را هرگز در سمت کاربر یا کد قابل‌مشاهده قرار ندهید؛ فقط در سرور نگه دارید.
• مبالغ همیشه به تومان و عدد صحیح‌اند. هیچ اطلاعاتی دربارهٔ نوع کالا ارسال یا ذخیره نمی‌شود.
• هر سفارش ۱۵ دقیقه فرصت پرداخت دارد؛ پس از آن توکن منقضی می‌شود.
• درگاه فقط برای وب‌سایتی فعال می‌شود که آدرس آن در پنل ثبت و توسط اعتباریت (با بررسی نماد اعتماد الکترونیکی) تأیید شده باشد. آدرس بازگشت نیز باید با https و روی همان دامنه باشد؛ در غیر این صورت درخواست با کد ۹- یا ۱۰- رد می‌شود.
• تحویل کالا یا خدمت را فقط پس از دریافت کد ۱۰۰ یا ۱۰۱ از «تأیید پرداخت» انجام دهید، نه صرفاً با بازگشت Callback.
• در صورت لو رفتن کلیدها، از پنل فروشگاه آن‌ها را بازتولید کنید؛ کلید قبلی بلافاصله باطل می‌شود.

افزونه‌های آماده

اگر از یکی از سیستم‌های زیر استفاده می‌کنید، به‌جای نوشتن افزونه، می‌توانید افزونهٔ آمادهٔ درگاه اعتباریت را دانلود و نصب کنید.