از اولین درخواست
تا اولین پرداخت.

نمونه‌کد متناسب با درخواست تو

مبلغ، مهلت و شناسهٔ فرم بالا در نمونه‌ها به‌روز می‌شوند. کلید از متغیر محیطی سرور خوانده می‌شود.

آدرس این سرویس:

شروع اتصال API

آدرس پایه API دامنه همین سرویس با مسیر /api/v1 است. کلید واقعی حساب پس از اتصال معتبر به بلو، خودکار در تنظیمات API پنل آماده می‌شود. آن را کپی و فقط روی سرور فروشگاه نگهداری کنید. گزینه تعویض کلید، دسترسی کلید قبلی را باطل می‌کند. محیط test برای آزمون و محیط live برای پرداخت واقعی است. نمونه‌های زیر درخواست‌ها و پاسخ‌های اتصال را نشان می‌دهند.

احراز هویت API

کلید فقط روی سرور فروشگاه نگهداری شود. هر کلید به یک حساب و محیط test یا live محدود است. درخواست از JavaScript مرورگر پذیرفته نمی‌شود. سقف هر کلید ۶۰ درخواست در دقیقه است؛ خطای 429 با Retry-After پاسخ داده می‌شود.

Authorization: Bearer db_live_YOUR_SERVER_KEY
Content-Type: application/json

ساخت فاکتور

POST /api/v1/invoices · amount_rial رشته عدد صحیح و مضرب ۱۰ است. order_id به‌صورت تصادفی و یکتا توسط سرور ساخته می‌شود و title نام ثبت‌شده فروشگاه است. request_id اختیاری، شناسه ثابت درخواست شماست؛ برای تکرار امن همان مقدار و مبلغ و مهلت را بفرستید. بدون request_id هر درخواست یک فاکتور تازه می‌سازد. مبلغ نهایی شامل افزوده کوچک یکتا است؛ مشتری باید amount_rial پاسخ را بپردازد.

{
  "request_id": "checkout-1001-attempt-1",
  "amount_rial": "100000",
  "presentation": "direct",
  "ttl_minutes": 30
}

تکرار امن درخواست و نام فروشگاه

request_id از ۱ تا ۱۰۰ نویسه انگلیسی، عدد یا _ . : - است و در محدوده حساب و محیط کلید نگهداری می‌شود. تغییر مبلغ، مهلت یا لینک برگشت اختصاصی با همان شناسه خطای request_id_conflict می‌دهد. برای تلاش پرداخت جدید شناسه تازه بسازید؛ شناسه را قبل از ارسال در فروشگاه ذخیره کنید. تغییر نام فروشگاه از تنظیمات فقط عنوان فاکتورهای جدید را تغییر می‌دهد. order_id و title ورودی قدیمی منسوخ‌اند؛ order_id قدیمی فقط نقش شناسه درخواست دارد و title ارسالی عنوان جدید را تغییر نمی‌دهد. request_id و order_id را همزمان نفرستید.

order_id تولیدشده، id و amount_rial نهایی پاسخ را کنار سفارش داخلی خود ذخیره کنید. وب‌هوک همان order_id را ارسال می‌کند. در خطای شبکه یا 5xx با فاصله و همان request_id تکرار کنید؛ در 429 مقدار Retry-After را رعایت کنید. خطای اعتبارسنجی را خودکار تکرار نکنید.

پرداخت در صفحه خود فروشنده

presentation=direct لینک آماده را در پاسخ ساخت null می‌کند. کارت، نام، مبلغ و زمان را روی صفحه خودتان نشان بدهید. GET /api/v1/invoices/{id}/payment-data همین اطلاعات را بدون payment_url برمی‌گرداند. برای سریع‌ترین اتصال، اطلاعات کارت، نام، مبلغ و انقضا را از همان پاسخ ساخت فاکتور با presentation=direct بگیرید؛ درخواست GET دوباره بلافاصله پس از ساخت لازم نیست. این مسیر درخواست بانک یا صفحه پرداخت را اجرا نمی‌کند. تأخیر اینترنت فروشگاه به زمان پاسخ اضافه می‌شود و تأیید واریز مرحله‌ای جدا است. رقم افزوده و زمان انقضا را تغییر ندهید. مبلغ تومانی نیز رشته است. نبود نام صاحب کارت را با تکمیل تنظیمات حساب رفع کنید.

{
  "id": "invoice-uuid",
  "order_id": "BA-550e8400-e29b-41d4-a716-446655440000",
  "mode": "live",
  "amount_rial": "100340",
  "amount_toman": "10034",
  "card_number": "CARD_FROM_SELLER_SETTINGS",
  "cardholder": "نام ثبت‌شده صاحب کارت",
  "expires_at": "2026-10-13T08:00:00.000Z",
  "expires_in_seconds": 1800,
  "status": "PENDING",
  "paid": false,
  "payment_url": null
}

وضعیت و تحویل سفارش

GET /api/v1/invoices/{id} · PENDING منتظر پرداخت، MATCHED_REVIEW نیازمند بررسی، PAID پرداخت تأییدشده، EXPIRED منقضی و CANCELED لغوشده است. status=PAID در محیط test پرداخت واقعی نیست. فقط mode=live و paid=true، پس از بررسی شناسه سفارش و مبلغ ذخیره‌شده و ثبت یکتای تحویل در پایگاه داده فروشگاه، مجوز تحویل است. بازخوانی وضعیت، درخواست تازه‌ای به بانک نمی‌فرستد.

پیگیری واریز با مبلغ رند

وقتی واریز قطعی و مصرف‌نشده‌ای در بازه زمانی فاکتور پیدا شود، صفحه پرداخت پاپ‌آپ پیگیری با دکمه «پرداخت کردم؛ تأیید نشده» را نشان می‌دهد. مبلغ اصلی سفارش یا مبلغ رند مضرب ۱۰٬۰۰۰ ریال با حداکثر ۱۰٬۰۰۰ ریال اختلاف بررسی می‌شود. مشتری چهار رقم آخر کارت مبدأ یا نام کامل واریزکننده را وارد می‌کند. در انتقال با شبا، چهار رقم آخر شبا پذیرفته نمی‌شود و فقط نام کامل بررسی می‌شود. برای انتقال بلو به بلو نیز مشتری باید روش نام کامل واریزکننده را انتخاب کند. اگر بررسی با کارت نتیجه نداد، دکمهٔ مستقیم بررسی با نام در پاپ‌آپ در دسترس است. پس از نتیجه ناموفق، تغییر بین روش کارت و نام نیاز به انتظار ۳۰ ثانیه‌ای ندارد؛ سقف پنج درخواست برای هر فاکتور حفظ می‌شود. دکمه برگشت، نتیجه قبلی و اطلاعات تایپ‌شده هر روش را حفظ می‌کند و تا زدن بررسی، درخواست جدیدی ارسال نمی‌شود.

نام پس از یکسان‌سازی حروف فارسی و فاصله‌ها به‌صورت دقیق مقایسه می‌شود؛ تطبیق تقریبی نام انجام نمی‌شود. چند واریز با هویت یکسان، اطلاعات ناقص، برداشت، واریز در انتظار یا خارج از مهلت خودکار تأیید نمی‌شود. هر واریز فقط برای یک فاکتور مصرف می‌شود و رزرو مبلغ دقیق فاکتور دیگر محفوظ است.

در GET فاکتور و وب‌هوک، amount_rial همچنان مبلغ درخواستی فاکتور است. مبلغ واقعی وصول‌شده در received_amount_rial و received_amount_toman می‌آید؛ پیش از تأیید، این دو فیلد در API مقدار null دارند. پس از تأیید قطعی، همان رویداد امضاشده invoice.paid ارسال می‌شود. مبلغ واقعی و اختلاف را در حسابداری ثبت کنید؛ پرداخت را دوباره ایجاد نکنید.

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

وب‌هوک امضاشده

POST /api/v1/webhook با {url,enabled} · فقط HTTPS سرور عمومی روی پورت ۴۴۳. کلید امضا فقط هنگام ایجاد نمایش داده می‌شود. رویداد invoice.paid پس از تأیید واقعی و کسر یکتای کارمزد، در همان تراکنش پایگاه داده ثبت می‌شود. ارسال دست‌کم یک‌بار است؛ گیرنده باید event_id را یکتا ثبت کند. پاسخ 2xx موفق محسوب می‌شود. timeout ده ثانیه، حداکثر ۸ تلاش با فاصله افزایشی تا یک ساعت؛ تغییرمسیر و مقصدهای داخلی پذیرفته نمی‌شوند. URL و کلید هر رویداد ثابت‌اند.

X-Didban-Event-Id: UUID
X-Didban-Timestamp: UNIX_SECONDS
X-Didban-Signature: v1=HEX_HMAC_SHA256

Signed message = timestamp + "." + exact_raw_body

{ "event_id":"UUID", "type":"invoice.paid", "data": {
  "id":"invoice-uuid", "order_id":"BA-550e8400-e29b-41d4-a716-446655440000",
  "mode":"live", "paid":true, "status":"PAID",
  "amount_rial":"100340", "amount_toman":"10034"
}}

وب‌هوک دستی؛ ارسال تمام واریزهای حساب

در مینی‌اپ، تنظیمات ← وب‌هوک دستی، هر فروشنده فقط یک لینک HTTPS ثبت می‌کند. هر واریز قطعی جدیدِ حساب متصل، با مبلغ کامل ریالی و مستقل از فاکتور، به همین لینک POST می‌شود؛ مبلغ رند، غیررند یا تکرار مبلغ باعث حذف رویداد نمی‌شود. برداشت، واریز در انتظار، دادهٔ واردشده از فایل و سوابق پیش از فعال‌سازی ارسال نمی‌شوند.

{
  "message": "واریز به حساب بلو\nمبلغ واریزی: 2029750 ریال",
  "sender": "BLUAUTO"
}

نام فیلدهای message و sender، نام فرستنده، قالب متن و پارامترهای متنی اضافی از پنل قابل تغییرند. قالب باید {{amount_rial}} داشته باشد. متغیرهای {{transaction_id}}، {{date}} و {{time}} نیز قابل استفاده‌اند. لینک جدید جایگزین تنها لینک قبلی می‌شود؛ صف ارسال‌نشده به آخرین لینک تنظیم‌شده ارسال می‌شود. پیام‌های در صف، قالب ثبت‌شدهٔ زمان ایجاد رویداد را نگه می‌دارند.

پاسخ HTTP از ۲۰۰ تا ۲۹۹ به معنی تحویل به گیرنده است، نه اثبات پردازش نهایی آن. در خطا، رویداد در پایگاه داده می‌ماند و با فاصلهٔ افزایشی تا یک ساعت دوباره تلاش می‌شود. هنگام خاموشی گزینه، صف قبلی محفوظ است ولی واریزهای همان بازه پیام تازه نمی‌سازند. دریافت لحظه‌ای به اتصال بلو و پاسخ گیرنده وابسته است.

تحویل از نوع at-least-once است: اگر گیرنده پردازش کرده ولی پاسخ در شبکه گم شود، تلاش مجدد ممکن است همان پیام را برساند. شناسهٔ ثابت در X-Bluauto-Event-Id و Idempotency-Key ارسال می‌شود؛ گیرنده باید قبل از اثرگذاری، این شناسه را با قید UNIQUE ذخیره کند. این پیام به‌تنهایی تأیید یک فاکتور bluauto نیست؛ برای تحویل سفارش از وب‌هوک امضاشدهٔ invoice.paid و استعلام API استفاده کنید.

گیرندهٔ پیامک با فیلدهای sms و key

در «تنظیمات ← وب‌هوک دستی ← قالب گیرنده»، گزینهٔ «پیامک با کلید ثابت / sms + key» را انتخاب کنید. آدرس HTTPS گیرنده و کلید امنیتی اعلام‌شده توسط آن را وارد و ذخیره کنید. درخواست با روش POST و Content-Type: application/json ارسال می‌شود. فیلد فرستنده در این قالب حذف می‌شود؛ اگر پارامتر اضافی دیگری تعریف نکنید، بدنه فقط دو فیلد زیر را دارد:

{
  "sms": "واریز به حساب بلو\nمبلغ واریزی: 2029750 ریال",
  "key": "YOUR_FIXED_SECURITY_KEY"
}

مقدار key متن ثابت است؛ نه براساس مبلغ تغییر می‌کند و نه متغیرهای قالب در آن جایگزین می‌شوند. فقط متن sms با تراکنش ساخته می‌شود. کلید واقعی را در پنل خصوصی وارد کنید و در کد عمومی یا داکیومنت قرار ندهید. ارسال دوبارهٔ یک رویداد همان بدنه و کلید ثبت‌شدهٔ زمان ایجاد آن را حفظ می‌کند. برای حذف فیلد فرستنده در قالب سفارشی نیز نام پارامتر فرستنده را خالی بگذارید.

ساخت وب‌هوک فروشگاه، قدم‌به‌قدم

1. یکی از فایل‌های کامل PHP، Python یا Node.js را روی سرور فروشگاه نصب کنید و مسیر HTTPS عمومی گیرنده را بسازید.
2. همین مسیر را در «تنظیمات ← وب‌هوک» پنل یا POST /api/v1/webhook ثبت و enabled را true کنید.
3. کلید secret پاسخ اولین ثبت را در BLUAUTO_WEBHOOK_SECRET سرور گیرنده بگذارید. کلید API و کلید وب‌هوک دو مقدار متفاوت‌اند.
4. BLUAUTO_WEBHOOK_DB را مسیر پایگاه داده بیرون پوشه عمومی وب تعیین کنید. پس از ساخت فاکتور، order_id، شناسه فاکتور و مبلغ نهایی ریالی پاسخ را پیش از نمایش پرداخت به مشتری ذخیره کنید.
5. فایل‌های نمونه امضای بدنه خام، اعتبار زمان و تطبیق سفارش را بررسی می‌کنند و دریافت رویداد، پرداخت سفارش و صف تحویل یکتا را در یک تراکنش ثبت می‌کنند. دریافت تکراری نباید تحویل دوباره بسازد.
6. با آزمون امضای خراب، مبلغ نامنطبق و ارسال دوباره شروع کنید. پس از ثبت پایدار، پاسخ 200 بدهید. خطای پایگاه داده باید پاسخ 503 بدهد تا ارسال تکرار شود.

Python و Node فقط روی localhost:8088 اجرا می‌شوند؛ برای دریافت واقعی باید پشت reverse proxy با HTTPS معتبر باشند. PHP روی وب‌سرور فروشگاه منتشر می‌شود. راهنمای فایل‌ها روش اجرا، تنظیم محیط، صف تحویل و پیگیری خطا را توضیح می‌دهد.

دست‌کاری پیام را تشخیص بده

یک پیام نمونه و امضای HMAC-SHA256 در مرورگر ساخته می‌شود. متن پیام را تغییر بده و دوباره اعتبارسنجی کن. این آزمایش محلی است؛ هیچ وب‌هوکی ارسال نمی‌شود. کلید این مثال ساختگی است.

بررسی امضا در PHP

بدنه خام را پیش از JSON decode استفاده کنید؛ timestamp را با حداکثر اختلاف ۵ دقیقه بررسی کنید. پس از امضا، فاکتور و مبلغ را با سفارش ذخیره‌شده تطبیق دهید؛ در صورت نیاز نتیجه فاکتور از API نیز قابل دریافت است. event_id و invoice_id و شناسه سفارش باید در فروشگاه یکتا باشند. خطای پردازش را 5xx برگردانید تا ارسال دوباره انجام شود. این نمونه سفارش را تحویل نمی‌دهد؛ ثبت اتمیک و یکتای تحویل در فروشگاه شما لازم است.

<?php
$raw = file_get_contents("php://input");
$t = $_SERVER["HTTP_X_DIDBAN_TIMESTAMP"] ?? "";
$sig = $_SERVER["HTTP_X_DIDBAN_SIGNATURE"] ?? "";
$secret = getenv("BLUAUTO_WEBHOOK_SECRET");
if (!$secret || !ctype_digit($t) || abs(time() - (int)$t) > 300) {
  http_response_code(401); exit;
}
$expected = "v1=" . hash_hmac("sha256", $t . "." . $raw, $secret);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }
$event = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
// Check event_id, live paid invoice, saved order and amount.
// Persist event and fulfill the order once in one DB transaction.
// Only then respond with 200.

پیگیری ارسال‌ها

GET /api/v1/webhook/events و بخش وب‌هوک پنل، شناسه رویداد، وضعیت ارسال، تعداد تلاش و کد HTTP را نشان می‌دهند. ارسال ناموفق پس از ۸ تلاش failed می‌شود و فروشنده در پنل یا با POST /api/v1/webhook/events/{event_id}/retry و بدنه {} می‌تواند ارسال همان رویداد شکست‌خورده را دوباره شروع کند. شناسه و بدنه رویداد در تکرار ثابت می‌مانند؛ timestamp و امضا برای هر ارسال تازه‌اند. تلاش بعدی با مقصد و کلید امضای فعلی فروشنده انجام می‌شود؛ بدنه و شناسه رویداد ثابت می‌مانند. این مسیر فقط رویداد حساب همان کلید را می‌پذیرد. key یا اطلاعات حساس در گزارش خطا ثبت نمی‌شوند.

کیف پول و خطاها

GET /api/v1/wallet · balance_toman موجودی، reserved_toman رزرو فاکتورهای باز و available_toman موجودی قابل استفاده است. کارمزد هنگام ساخت فاکتور واقعی رزرو و هنگام تأیید یک بار کم می‌شود. لغو فاکتور رزرو را آزاد می‌کند. رزرو فاکتور منقضی تا ۲۴ ساعت نگهداری می‌شود تا دریافت دیرهنگام واریز داخل مهلت قابل تسویه باشد. فاکتور آزمایشی کارمزد ندارد. موجودی قابل استفاده کمتر از ۲٬۵۰۰ تومان یا تأییدنشدن فروشگاه، ساخت دستی/API را متوقف می‌کند.

seller_not_approved
initial_topup_required
insufficient_wallet_balance
invalid_api_key
invoice_not_found
rate_limited

نمونه زبان‌ها

کلاینت‌های PHP، Python، Node.js، Go و C# از لینک‌های زیر قابل دریافت‌اند. API_URL را روی دامنه HTTPS سرور نهایی تنظیم کنید. نمونه‌ها، کلید یا اطلاعات واقعی داخل خود ندارند.

افزونه وردپرس و ووکامرس · نسخه ۲

پنل فارسی مستقل با تنظیم اتصال، ثبت و تست وب‌هوک، گزارش پرداخت‌ها، جست‌وجو و فیلتر، خروجی CSV، ساخت شورت‌کد، رسید خریدار و پیگیری دوره‌ای دارد. پرداخت کلاسیک، Checkout Blocks و HPOS پشتیبانی می‌شوند. PHP ۸٫۱ یا جدیدتر، OpenSSL، HTTPS و MySQL/MariaDB با GET_LOCK لازم است؛ واحد سفارش IRR یا IRT/TMN باشد.

دریافت افزونه ZIP

1. ZIP را در وردپرس ← افزونه‌ها ← افزودن ← بارگذاری نصب و فعال کنید.
2. در منوی bluauto ← اتصال و وب‌هوک، دامنه HTTPS سرویس و کلید API فروشنده را وارد و تست کنید.
3. وب‌هوک امضاشده فاکتورها را از همان صفحه ثبت و کلید امضا را ذخیره کنید؛ ثبت وب‌هوک دستی پیامکی جای آن را نمی‌گیرد.
4. در ووکامرس ← پیکربندی ← پرداخت‌ها، bluauto را فعال کنید و یک سفارش کوچک واقعی را تا دریافت وب‌هوک بررسی کنید.

شماره سفارش و شناسه درخواست خودکار ساخته می‌شوند. درخواست ناموفق با همان شناسه تکرار می‌شود. مبلغ نهایی یکتا در صفحه پرداخت نمایش داده می‌شود. برگشت مرورگر باعث تأیید سفارش نمی‌شود؛ گیرنده امضا، مبلغ، سفارش و وضعیت زنده را بررسی و فاکتور را دوباره از API استعلام می‌کند.

وردپرس بدون ووکامرس

[bluauto_pay amount="50000" currency="IRT" label="پرداخت"]

این شورت‌کد قدیمی همچنان کار می‌کند؛ برای مبلغ دلخواه از [bluauto_pay amount="custom"] استفاده کنید. حداقل، حداکثر، واحد مبلغ، رنگ فرم و رسید و برگه ادامه در تنظیمات قابل انتخاب‌اند. بعد از ارتقا کش برگه‌ها را پاک کنید. پیگیری دوره‌ای در سایت کم‌ترافیک به زمان‌بندی هاست نیاز دارد. ثبت پرداخت مستقل به‌تنهایی محصول یا اشتراک تحویل نمی‌دهد؛ هوک امن توسعه در README توضیح داده شده است. تنظیمات و سوابق نسخه قبلی حفظ می‌شوند.

آزمون اتصال وب‌هوک

POST /api/v1/webhook/test
Authorization: Bearer YOUR_SERVER_API_KEY
Content-Type: application/json

{}

این مسیر و مسیرهای تنظیم و جزئیات وب‌هوک فقط کلید live می‌پذیرند. ابتدا مقصد وب‌هوک را در مینی‌اپ ذخیره و فعال کنید. این درخواست یک رویداد امضاشده webhook.test با mode=test و paid=false در صف پایدار می‌گذارد. گیرنده پس از بررسی امضا و زمان، این نوع را با پاسخ ۲۰۰ تأیید کند و هیچ سفارش یا موجودی را تغییر ندهد. فهرست ارسال‌ها را از GET /api/v1/webhook/events و جزئیات هر رویداد، بدنه و تاریخچه تمام تلاش‌ها را از GET /api/v1/webhook/events/{event_id} یا جزئیات پنل دریافت کنید. جزئیات شامل کلید امضا نمی‌شود. افزونه وردپرس این رویداد را پشتیبانی می‌کند.

پیش از فعال‌سازی پرداخت واقعی

1. شناسه درخواست را پیش از ارسال ذخیره کن و رفتار تکرار درخواست را تست کن.
2. مبلغ نهایی و شناسه پاسخ را کنار سفارش فروشگاه نگه دار.
3. گیرنده وب‌هوک را با امضای خراب، رویداد تکراری و مبلغ نامنطبق آزمایش کن.
4. تحویل سفارش فقط پس از mode=live و paid=true و به‌صورت یکتا انجام شود.