شروع سریع

این صفحه برای کسانی است که می‌خواهند در کوتاه‌ترین زمان ممکن اولین تراکنش را بزنند. در پایان این پنج دقیقه، یک بک‌اند ساده دارید که URL پرداخت را تولید و تراکنش را Verify می‌کند.

مرحله ۱: دریافت کلید درگاه

1. در باسلام  ثبت‌نام کنید.
2. احراز هویت توسعه‌دهنده را در پنل  تکمیل کنید.
3. از بخش هسته مالی، درگاه پرداخت اینترنتی  کلید امنیتی درگاه خود را دریافت کنید. (X-Gateway-Secret)

مرحله ۲: ایجاد پیش‌تراکنش

درخواست (Request)

POST https://openapi.basalam.com/v1/pay/pre-transactions
X-Gateway-Secret: your_gateway_secret
Content-Type: application/json

{
  "reference_id": "ORDER-20260515-12345",
  "amount": 500000,
  "callback_url": "https://yoursite.com/payment/callback",
  "description": "خرید اشتراک ماهانه پلن طلایی"
}

پارامترها

پاسخ موفق (200 OK)

{
  "hash_id": "a1b2c3d4e5f6",
  "pay_url": "https://apps.basalam.com/pay/a1b2c3d4e5f6",
  "order": {
    "amount": 500000,
    "customer_fee": 5000,
    "customer_fee_percentage": 100,
    "merchant_fee": 0,
    "merchant_fee_percentage": 0,
    "total_fee": 5000,
    "total_amount": 505000,
  },
  "expired_at": "2026-05-15T12:30:00Z",
  "gateway": {
    "title": "فروشگاه شما",
    "logo": "https://cdn.basalam.com/logos/your-logo.png"
  },
  "pay_methods": [
    { "id": 1, "title": "کیف پول باسلام", "driver": "wallet", "enabled": true },
    { "id": 2, "title": "تراز غرفه", "driver": "balance", "enabled": false },
    { "id": 3, "title": "پرداخت آنلاین", "driver": "online", "enabled": true }
  ]
}

فیلدهای مهم پاسخ

• hash_id: شناسه پیش‌تراکنش — در دیتابیس ذخیره کنید
• pay_url: لینک صفحه پرداخت — کاربر را به اینجا هدایت کنید
• order.total_amount: مبلغ نهایی شامل کارمزد
• expired_at: زمان انقضا — پس از این زمان پیش‌تراکنش غیرفعال می‌شود
• pay_methods: روش‌های پرداخت فعال برای درگاه شما

خطاهای احتمالی

نکات پیاده‌سازی

1. ذخیره‌سازی: hash_id را با order_id در دیتابیس مرتبط کنید
2. Idempotency: قبل از ایجاد پیش‌تراکنش جدید، بررسی کنید که آیا برای این سفارش قبلاً ایجاد شده یا نه
3. مبلغ: همیشه به ریال ارسال کنید (۱ تومان = ۱۰ ریال)
4. Timeout: برای درخواست HTTP حداقل ۳۰ ثانیه timeout تنظیم کنید
5. این endpoint را فقط از سرور خود فراخوانی کنید. هرگز از کلاینت (مرورگر یا اپلیکیشن موبایل) صدا نزنید.

مرحله ۳: هدایت کاربر به صفحه پرداخت

پس از دریافت موفقیت‌آمیز pay_url، کاربر را به این آدرس هدایت کنید.

تجربه کاربری در صفحه پرداخت

1. کاربر وارد صفحه پرداخت باسلام می‌شود
2. اطلاعات سفارش (مبلغ، توضیحات، لوگوی فروشگاه) نمایش داده می‌شود
3. روش‌های پرداخت موجود نمایش داده می‌شود:
   • کیف پول باسلام (id: 1): پرداخت فوری از موجودی کیف پول
   • تراز غرفه (id: 2): پرداخت از تراز غرفه (فقط برای فروشندگان)
   • پرداخت آنلاین (id: 3): پرداخت با کارت بانکی
4. کاربر روش پرداخت را انتخاب و تایید می‌کند
5. در صورت انتخاب پرداخت آنلاین، به درگاه بانک هدایت می‌شود
6. پس از تکمیل، به callback_url شما بازمی‌گردد

پارامترهای Callback URL

کاربر با پارامترهای زیر به callback_url شما بازمی‌گردد:

https://yoursite.com/payment/callback?status=success&hash_id=a1b2c3d4e5f6

⚠️ هشدار امنیتی: هرگز به پارامترهای URL اعتماد نکنید. حتماً از endpoint استعلام استفاده کنید

مرحله ۴: استعلام وضعیت (اختیاری)

درخواست (Request)

GET https://openapi.basalam.com/v1/pay/transactions/{hash_id}/inquiry
X-Gateway-Secret: your_gateway_secret

پاسخ موفق (200 OK)

{
  "hash_id": "a1b2c3d4e5f6",
  "reference_id": "ORDER-20260515-12345",
  "amount": 505000,
  "status": {
    "id": 3,
    "title": "موفق",
    "slug": "success"
  },
  "callback_url": "https://yoursite.com/payment/callback?status=success&hash_id=a1b2c3d4e5f6",
  "expired_at": null,
  "created_at": "2026-05-15T11:00:00Z",
  "gateway": {
    "title": "فروشگاه شما",
    "logo": "https://cdn.basalam.com/logos/your-logo.png"
  }
}

خطاهای احتمالی

وضعیت‌های تراکنش

جزئیات وضعیت‌ها

success (موفق)

• پرداخت کامل شده و تایید شده است
• می‌توانید سفارش را تحویل دهید
• این وضعیت قطعی است و تغییر نمی‌کند (مگر در صورت refund)

failed (ناموفق)

• پرداخت انجام نشده یا رد شده است
• دلایل احتمالی: موجودی کافی نبوده، کاربر پرداخت را لغو کرده، خطا در درگاه بانک
• سفارش را لغو کنید

unverified (تایید نشده) ⚠️

• مهم‌ترین وضعیت برای مدیریت
• پول از حساب کاربر کسر شده اما تایید نهایی از شما دریافت نشده
• متد وریفای تراکنش را باید صدا بزنید

pending و processing

• وضعیت‌های موقت
• در انتظار پرداخت کاربر و بازگشت از درگاه

مرحله ۵: وریفای (تایید) تراکنش

زمان استفاده

این endpoint برای زمانی است که:

• تراکنش در وضعیت unverified است
• می‌خواهید به صورت دستی یا از طریق جاب چک، تراکنش را تایید کنید

درخواست (Request)

POST https://openapi.basalam.com/v1/pay/transactions/{hash_id}/verify
X-Gateway-Secret: your_gateway_secret

پاسخ موفق (200 OK)

{
  "hash_id": "a1b2c3d4e5f6",
  "reference_id": "ORDER-20260515-12345",
  "amount": 505000,
  "status": {
    "id": 3,
    "title": "موفق",
    "slug": "success"
  },
  "callback_url": "https://yoursite.com/payment/callback?status=success&hash_id=a1b2c3d4e5f6",
  "expired_at": null,
  "created_at": "2026-05-15T11:00:00Z",
  "gateway": {
    "title": "فروشگاه شما",
    "logo": "https://cdn.basalam.com/logos/your-logo.png"
  }
}

خطاهای احتمالی

نکات پیاده‌سازی

1. فقط برای unverified: این endpoint فقط برای تراکنش‌های unverified کار می‌کند
2. Idempotent: اگر تراکنش قبلاً verify شده باشد، خطای ۴۲۲ برمی‌گرداند
3. در جاب چک: این endpoint را در background job برای تایید خودکار استفاده کنید

مرحله ۵: جاب چک تراکنش‌های تایید نشده

وضعیت unverified نیاز به پیگیری خودکار دارد. باید یک background job پیاده‌سازی کنید که به صورت دوره‌ای تراکنش‌های تایید نشده را چک و verify کند.

استراتژی پیشنهادی

هر ۵ دقیقه یک‌بار

1. لیست تراکنش‌های unverified را از API بگیر
2. برای هر تراکنش verify بزن
3. وضعیت را در DB آپدیت کن
4. اگر success شد → سفارش را تایید کن
5. اگر failed شد → سفارش را لغو کن
6. اگر هنوز unverified → در صف نگه دار

روال صحیح جاب چک

1. دریافت لیست: از GET /v1/pay/transactions/unverified لیست تراکنش‌های unverified را بگیرید
2. تایید دستی: برای هر تراکنش POST /v1/pay/transactions/{hash_id}/verify بزنید
3. بروزرسانی: وضعیت را در دیتابیس خود آپدیت کنید
4. اطلاع‌رسانی: در صورت موفقیت، به کاربر اطلاع دهید

قوانین مهم

1. بازه زمانی: هر ۵ دقیقه یک‌بار چک کنید
2. Pagination: اگر تعداد تراکنش‌های unverified زیاد است، از pagination استفاده کنید
3. Rate Limiting: بین هر درخواست ۰.۵ ثانیه صبر کنید
4. Exponential Backoff: برای جلوگیری از overload:
   • اولین چک: بعد از ۵ دقیقه
   • دومین چک: بعد از ۱۰ دقیقه
   • سومین چک: بعد از ۲۰ دقیقه
   • و به همین ترتیب تا حداکثر ۱ ساعت
5. حداکثر زمان: تا ۲۴ ساعت بعد از ایجاد تراکنش ادامه دهید
6. بعد از ۲۴ ساعت: اگر هنوز unverified بود، با پشتیبانی تماس بگیرید

نکات پیاده‌سازی جاب چک

1. Logging: تمام عملیات را لاگ کنید
2. Monitoring: تعداد تراکنش‌های unverified را مانیتور کنید
3. Alert: اگر تعداد unverified از حد معینی گذشت، هشدار بدهید
4. Retry Logic: در صورت خطای شبکه، دوباره تلاش کنید
5. Dead Letter Queue: تراکنش‌های بیش از ۲۴ ساعت را جدا کنید