مستندات فاکتور واسط بیت‌لنسر

شروع سریع

1. در بیت‌لنسر ثبت‌نام کرده و احراز هویت اولیه خود را تکمیل کنید.
2. از صفحه‌ی فاکتور واسط در پروفایل خود، یک کلید API بسازید.
3. با همان کلید، درخواست‌های زیر را از سرور خودتان (نه از داخل مرورگر کاربر) به آدرس‌های این صفحه بزنید.

احراز هویت

همه‌ی درخواست‌ها باید کلید API شما را در هدر Authorization به‌صورت زیر داشته باشند. کلید API با نشست ورود کاربران متفاوت است و مخصوص استفاده‌ی سرور به سرور (ربات، بک‌اند سایت شما) طراحی شده؛ هرگز آن را در کد سمت کاربر (فرانت‌اند/اپلیکیشن موبایل) قرار ندهید.

Authorization: Bearer blk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

ساخت فاکتور

نمونه درخواست - قیمت ثابت به TRX (برای فروشندگانی که خودشان قیمت را به TRX تعیین می‌کنند)

curl -X POST https://api.bitlancer.ir/api/v1/invoices \
  -H "Authorization: Bearer blk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "title": "خرید اشتراک ویژه",
    "fee_payer": "payer",
    "external_id": "order-4821",
    "callback_url": "https://yourbot.example.com/webhook"
  }'

نمونه درخواست - قیمت ثابت به تومان (برای فروشگاه‌هایی با قیمت‌های متفرقِ تومانی)

curl -X POST https://api.bitlancer.ir/api/v1/invoices \
  -H "Authorization: Bearer blk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_toman": 500000,
    "title": "خرید کفش مدل X",
    "fee_payer": "payer",
    "external_id": "order-4821",
    "callback_url": "https://yourbot.example.com/webhook"
  }'

نمونه پاسخ (201)

{
  "invoice": {
    "token": "SdVh5OTnbzBD6hZkAOx4ltnX",
    "external_id": "order-4821",
    "title": "خرید کفش مدل X",
    "amount": 500000,
    "currency": "TMN",
    "fee_payer": "payer",
    "status": "open"
  },
  "payment_link": "https://bitlancer.ir/invoice/SdVh5OTnbzBD6hZkAOx4ltnX",
  "bot_payment_link": "https://t.me/bitlancerirbot?start=pay_SdVh5OTnbzBD6hZkAOx4ltnX"
}

استعلام وضعیت فاکتور

curl https://api.bitlancer.ir/api/v1/invoices/SdVh5OTnbzBD6hZkAOx4ltnX \
  -H "Authorization: Bearer blk_live_XXXX"

{
  "invoice": {
    "token": "SdVh5OTnbzBD6hZkAOx4ltnX",
    "external_id": "order-4821",
    "title": "خرید اشتراک ویژه",
    "amount": "10.00000000",
    "currency": "TRX",
    "fee_payer": "payer",
    "status": "paid",
    "webhook_status": "sent",
    "created_at": "2026-09-20T18:56:54.000000Z",
    "updated_at": "2026-09-20T19:02:11.000000Z"
  }
}

مقدار status یکی از سه حالت open (در انتظار پرداخت)، paid (پرداخت‌شده) یا cancelled (لغوشده) است. اگر پرداخت با کارت‌به‌کارت انجام شده باشد، تا زمان تأیید دستی مدیر بیت‌لنسر همچنان open باقی می‌ماند.

وب‌هوک پرداخت

به‌محض تکمیل پرداخت (چه از طریق درگاه، چه پس از تأیید کارت‌به‌کارت)، یک درخواست POST به آدرس callback_url شما ارسال می‌شود:

POST https://yourbot.example.com/webhook
X-Bitlancer-Signature: sha256=1f4a3c...
Content-Type: application/json

{
  "event": "invoice.paid",
  "invoice": {
    "token": "SdVh5OTnbzBD6hZkAOx4ltnX",
    "external_id": "order-4821",
    "amount": 10,
    "status": "paid",
    "paid_at": "2026-09-20T19:02:11+00:00"
  }
}

برای اطمینان از اینکه درخواست واقعاً از طرف بیت‌لنسر آمده، هدر X-Bitlancer-Signature را بررسی کنید: مقدار آن، هش HMAC-SHA256 بدنه‌ی خام درخواست است که با کلید API شما امضا شده است.

نمونه تأیید امضا (PHP)

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $apiKey);

if (!hash_equals($expected, $_SERVER['HTTP_X_BITLANCER_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

الگوی پیشنهادی یکپارچه‌سازی: استعلام دوره‌ای وضعیت

چون تحویل وب‌هوک تک‌تلاشه است و اگر سرور شما لحظه‌ای در دسترس نباشد ممکن است هرگز نرسد، پیشنهاد ما این است که به‌جای تکیه‌ی صرف روی callback_url، وضعیت فاکتور را خودتان به‌صورت دوره‌ای استعلام بگیرید (وب‌هوک را هم می‌توانید کنارش نگه دارید، برای اطلاع سریع‌تر - ولی نه تنها منبع تشخیص پرداخت).

روند کار

1. فاکتور را با POST /invoices بسازید (فرقی نمی‌کند callback_url بدهید یا نه - استعلام دوره‌ای مستقل از آن کار می‌کند).
2. بلافاصله بعد از ساخت فاکتور، استعلام GET /invoices/{token} را با یک فاصله‌ی زمانی ثابت شروع کنید.
3. بر اساس مقدار status در پاسخ عمل کنید:
   • open ← همچنان در انتظار؛ به استعلام ادامه دهید.
   • paid ← استعلام را متوقف کنید، سفارش را «پرداخت‌شده» علامت بزنید و محصول/خدمت را تحویل دهید.
   • cancelled ← استعلام را متوقف کنید و به مشتری اطلاع دهید فاکتور لغو شده است.
4. یک سقف زمانی هم در نظر بگیرید (مثلاً ۳۰ دقیقه) - اگر فاکتور بعد از این مدت هنوز open بود، استعلام را متوقف کرده و آن را در سیستم خودتان منقضی‌شده در نظر بگیرید (مشتری می‌تواند فاکتور جدید درخواست کند).

پارامترهای پیشنهادی

• فاصله‌ی استعلام: هر ۱۵ ثانیه (به‌اندازه‌ی کافی سریع، و در عین حال در محدوده‌ی معقول درخواست‌ها).
• سقف زمانی: ۳۰ دقیقه برای هر فاکتور.
• برای استعلام هم از همان هدر Authorization: Bearer <api_key> استفاده کنید.

همین الگو برای ربات تلگرام بیت‌لنسر پیاده‌سازی شده و تشخیص تأیید پرداخت را کاملاً با همین استعلام دوره‌ای انجام می‌دهد - بدون نیاز به هیچ endpoint عمومی HTTP در سمت خودش.

احراز هویت پرداخت‌کننده

مشتری شما هم برای پرداخت فاکتور باید یک کاربر بیت‌لنسر باشد (اگر نباشد، هنگام باز کردن لینک به ثبت‌نام هدایت می‌شود). سطح احراز هویت لازم بر اساس ارزش دلاری فاکتور تعیین می‌شود:

• تا سقف مشخص‌شده در تنظیمات پلتفرم (پیش‌فرض ۱۵ دلار): احراز هویت اولیه کافی است.
• بالاتر از این سقف: پرداخت‌کننده باید احراز هویت پیشرفته (نهایی) را هم تکمیل کرده باشد.

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

کدهای خطا

نکات و محدودیت‌ها

• در حال حاضر فاکتورها فقط به ارز ترون (TRX) قابل ساخت هستند.
• مبلغ ریالی که پرداخت‌کننده می‌بیند، بر اساس نرخ لحظه‌ای TRX محاسبه و در لحظه‌ی پرداخت قفل می‌شود.
• درصد کارمزد پلتفرم توسط بیت‌لنسر تعیین می‌شود و در لحظه‌ی ساخت هر فاکتور روی همان فاکتور ثبت می‌شود.
• هر کاربر یک کلید API فعال دارد؛ ساخت کلید جدید، کلید قبلی را بلافاصله غیرفعال می‌کند.

پشتیبانی

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