API یکپارچه و ارز دیجیتال

این فایل مکمل API-REFERENCE.md هست (که فقط کارت‌به‌کارت رو پوشش می‌ده). اینجا endpointهای مربوط به ارز دیجیتال و روتر یکپارچه (کارت + کریپتو، انتخاب با مشتری) توضیح داده می‌شه.

📌 اگه فقط از ووکامرس استفاده می‌کنید، لازم نیست این فایل رو بخونید — کافیه تو تنظیمات افزونه، «آدرس سرور یکپارچه» رو هم پر کنید. این مستندات برای اتصال مستقیم (بدون افزونه) یا ساخت اتصال سفارشیه.

🚀 endpoint پیشنهادی: ساخت سفارش یکپارچه

Endpoint:

POST https://cubevps.ir/pay/create-order.php

بسته به تنظیمات فروشنده («🏪 فروشگاه من → 💳 روش‌های پرداخت» تو ربات)، این endpoint خودش تصمیم می‌گیره: - فقط کارت فعاله → مستقیم فاکتور کارتی می‌سازه و لینکش رو می‌ده - فقط کریپتو فعاله → مستقیم فاکتور کریپتویی می‌سازه - هر دو فعاله → یه لینک به صفحه‌ی «کارت یا کریپتو؟» می‌ده؛ مشتری انتخاب می‌کنه و از همون‌جا به فاکتور واقعی هدایت می‌شه

📋 پارامترها

✅ نمونه پاسخ

{
  "success": true,
  "method": "card",
  "pay_page_url": "https://cubevps.ir/smspay/pay.php?authority=...",
  "authority": "bdc9e0497c..."
}

وقتی method برابرِ card باشه، پاسخ این فیلدها رو هم داره — برای وقتی که می‌خواید پرداخت رو به‌جای صفحه‌ی وب، داخلِ رباتِ خودتون نشون بدید:

{
  "card": { "number": "6219861900412221", "holder": "نام صاحب کارت", "sheba": null },
  "pay_amount_toman": 24322,
  "expires_at": "2026-09-11T18:27:00+03:30",
  "expires_in_minutes": 30,
  "show_card_in_bot": false
}

show_card_in_bot همون تنظیمِ «🤖 نمایش کارت در ربات» تو حسابِ خودتونه که سرور بهتون اعلامش می‌کنه. نمونه‌ی آماده: نمایش پرداخت داخل ربات. ⚠️ اگر «چرخش کارت» روشن باشه، هر فاکتور ممکنه کارتِ متفاوتی بگیره — همیشه همون کارتی رو نشون بدید که تو پاسخِ همین فاکتور اومده. 👉 چه کسی باید چه کاری بکند: نمایش کارت داخل ربات.

مقدار method می‌تونه card, crypto, یا choice باشه. برای choice، فیلد authority وجود نداره (چون هنوز روش مشخص نشده) — نتیجه‌ی نهایی رو فقط از طریق callback_url یا با check-order-status.php زیر می‌فهمید.

🔍 استعلام وضعیت سفارش (Check Order Status)

Endpoint:

GET https://cubevps.ir/pay/check-order-status.php?order_id=YOUR_ORDER_ID

با هدر Authorization: Bearer YOUR_API_TOKEN.

تنها راهیه که فارغ از این‌که مشتری کارت انتخاب کرده، کریپتو، یا هنوز تصمیم نگرفته، با یه فراخوانی و بر پایه‌ی order_id خودتون وضعیت رو بگیرید — بدون نیاز به webhook. برای مسیر کریپتو و مسیر انتخاب همیشه کار می‌کنه.

✅ نمونه پاسخ‌ها

{ "success": true, "status": "choosing_method" }

{ "success": true, "method": "card", "status": "verified" }

{ "success": true, "method": "crypto", "status": "waiting" }

مقادیر ممکن برای status:

فقط verified (کارت) و finished (کریپتو) به معنای «پرداخت قطعی»ه — بقیه رو در انتظار یا ناموفق در نظر بگیرید.

⚠️ استثنا — مسیر فقط-کارتیِ مستقیم: اگه فقط کارت فعال باشه (بدون کریپتو)، این endpoint جواب نمی‌ده (success: false)، چون اون مسیر فقط با authority قابل پیگیریه، نه order_id. برای اون حالت، از verify-payment.php با همون authority که از پاسخ create-order.php گرفتید استفاده کنید.

راهکار ساده برای پوشش هر سه حالت با یه تابع: اول check-order-status.php رو با order_id امتحان کنید؛ اگه success: false برگردوند، به‌عنوان fallback با authority سراغ verify-payment.php برید.

🪙 endpointهای مستقیمِ ارز دیجیتال (اگه نمی‌خواید از روتر یکپارچه استفاده کنید)

ساخت فاکتور کریپتویی

POST https://cubevps.ir/crypto/api/create-crypto-payment.php

مشتری خودش تو صفحه‌ی برگشتی (pay_page_url) ارز (USDT-BEP20 / TRX / TON) رو انتخاب می‌کنه — این endpoint فوراً آدرس واریز نمی‌سازه، فقط یه فاکتور «در انتظار انتخاب ارز» می‌سازه.

چک وضعیت (Polling، اختیاری)

GET https://cubevps.ir/crypto/api/check-crypto-payment-status.php?token=XXXX

⚠️ چرا token بهتر از payment_idه: token یه رشته‌ی تصادفیِ غیرقابل‌حدسه، ولی payment_id یه شناسه‌ی عددیِ ساده‌ست که با امتحان‌کردن اعداد پشت‌سرهم قابل حدس زدنه — یعنی بدون token، تئوری هرکسی می‌تونست وضعیتِ فاکتورهای بقیه‌ی فروشنده‌ها رو هم فقط با امتحان کردن شماره ببینه. تا حد امکان payment_id رو تو URL عمومی (که به مرورگر مشتری داده می‌شه) قرار ندید.

🔄 اطلاعات ارسالی به callback_url

برای پرداخت کارتی

دقیقاً مثل API-REFERENCE.md — شامل authority. برای تایید نهایی، verify-payment.php رو صدا بزنید.

برای پرداخت کریپتویی

{
  "success": true,
  "status": "paid",
  "order_id": "ORD123",
  "payment_id": "4546796864",
  "pay_currency": "usdtbsc",
  "amount": "0.26",
  "sig": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

(هم به‌صورت POST با بدنه‌ی JSON، هم querystring GET روی همون آدرس)

مقدار status می‌تونه paid, failed, یا expired باشه.

⚠️ حتماً امضا (sig) رو چک کنید

چون این کال‌بک به سایت شما (که یه آدرس عمومیه) می‌رسه، هرکسی می‌تونه تئوری یه درخواست جعلی به همون آدرس بفرسته. برای اطمینان از اصالتش، sig رو با کلید API token خودتون دوباره بسازید و مقایسه کنید:

$expectedSig = hash_hmac('sha256', $orderId . '|' . $status . '|' . $amount, $apiToken);
if (!hash_equals($expectedSig, $sig)) {
    // جعلیه — نادیده بگیرید
    exit;
}

اگه امضا مطابقت نداشت، اون درخواست رو کاملاً نادیده بگیرید و سفارش رو «پرداخت‌شده» نکنید.

🔁 تلاش مجدد در صورت شکست

اگه سرور شما لحظه‌ای در دسترس نباشه یا با کد غیر ۲xx جواب بده، این کال‌بک تا ۳ بار با فاصله دوباره ارسال می‌شه. با این حال، شبکه همیشه غیرقابل پیش‌بینیه — برای اطمینان کامل، پیشنهاد می‌کنیم: - سریع (بدون پردازش سنگین) با کد ۲xx به کال‌بک جواب بدید تا تلاش بعدی لازم نشه. - علاوه بر تکیه به کال‌بک، یه بررسی دوره‌ای (مثلاً هر چند دقیقه، برای سفارش‌های هنوز «در انتظار») با check-order-status.php هم داشته باشید — این‌جوری حتی اگه هر ۳ تلاش کال‌بک هم به هر دلیلی شکست خورد (مثلاً سرورتون دقیقاً همون لحظه ری‌استارت شده بود)، خودتون فعال‌سازی رو نهایی می‌کنید.

⚠️ نکات مهم

• برخلاف endpointهای کارتی (که مبلغ رو به ریال می‌گیرن)، همه‌ی endpointهای کریپتویی/یکپارچه مبلغ رو به تومان می‌گیرن.
• هر پرداخت (کارتی یا کریپتویی) ۶۰ دقیقه اعتبار داره.
• هر ارز کریپتو یه حداقل مبلغ مجاز داره (چند ده هزار تومان بسته به نرخ روز) — اگه مبلغ کمتر باشه، پیام خطای روشن برمی‌گرده.
• کارمزد پلتفرم از پرداخت‌های کریپتویی به‌صورت درصدی محاسبه می‌شه (نه مبلغ ثابت تومانی مثل کارتی).