مستندات API

احراز هویت (HMAC)

هر درخواست API باید این headerها را داشته باشد:

• X-Api-Key — کلید API از پنل کسب و کار
• X-Timestamp — زمان Unix (حداکثر ±۵ دقیقه اختلاف)
• X-Signature — امضای HMAC-SHA256

فرمت امضا:

payload = timestamp + "\n" + METHOD + "\n" + path + "\n" + body
signature = HMAC-SHA256(api_secret, payload)

برای GET، body رشته خالی است. path شامل query string می‌شود.

ایجاد تراکنش

POST https://variznow.ir/api/v1/transactions/createContent-Type: application/json

{
  "order_id": "ORDER-1001",
  "amount": 1000000,
  "callback_url": "https://yoursite.com/payment/callback",
  "description": "خرید محصول",
  "customer_mobile": "09123456789"
}

amount به ریال. callback_url الزامی.

اگر order_id قبلاً منقضی یا ناموفق بوده، تراکنش تمدید می‌شود و gateway_url جدید برمی‌گردد. اگر هنوز باز (pending) باشد، همان لینک قبلی برگردانده می‌شود. برای سفارش paid خطای 409 می‌گیرید. با پایان زمان پرداخت، کاربر به callback_url با پارامتر status=expired هدایت می‌شود.

وضعیت تراکنش

GET https://variznow.ir/api/v1/transactions/status?order_id=ORDER-1001
GET https://variznow.ir/api/v1/transactions/status?transaction_id=123

وضعیت‌ها: pending | paid | expired | failed

Callback پرداخت موفق

بعد از تأیید SMS، POST JSON به callback_url ارسال می‌شود.

{
  "transaction_id": 123,
  "order_id": "ORDER-1001",
  "amount": 1000000,
  "unique_amount": 1000127,
  "status": "paid",
  "signature": "..."
}

امضا: فیلد signature را حذف کنید، ksort + json_encode + HMAC-SHA256 با api_secret.

فوروارد SMS به سرشماره (روش جدید)

بدون شورتکات: SMS بانک را به سرشماره واریزنو فوروارد کنید. سیستم از روی شماره فرستنده، کسب و کار را تشخیص می‌دهد و مبلغ را با تراکنش باز تطبیق می‌دهد.

Endpoint وب‌هوک ارائه‌دهنده SMS:

POST/GET https://variznow.ir/api/v1/sms/forward
from=0912...&to=SHORTCODE&text=واریز مبلغ 1,000,127 ریال به کارت ...

پارامترهای رایج: from (شماره فرستنده)، to (سرشماره)، text (متن پیام). متد POST یا GET.

فعال‌سازی در پنل کسب و کار → درگاه واریزنو → فوروارد اس‌ام‌اس — (نیاز به ورود)

دریافت SMS از گوشی (اتصال API به گوشی)

برای ارسال SMS واریز از گوشی کسب و کار به سرور با Device Token (از پنل: اتصال API به گوشی).

POST https://variznow.ir/api/v1/sms/incomingContent-Type: application/json

{
  "token": "YOUR_DEVICE_TOKEN",
  "message": "واریز مبلغ 1,000,127 ریال به کارت ..."
}

برای Shortcut iOS، token و message را در body JSON بفرستید. header X-Device-Token هم پشتیبانی می‌شود.

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

{"success": true, "data": {"matched": true, "transaction_id": 123, "status": "paid"}}

بدون match (422): SMS دریافت شد ولی تراکنش pending با آن مبلغ نبود.

راهنمای Shortcut iOS و اندروید: پنل کسب و کار → اتصال API به گوشی → راهنما (نیاز به ورود)

$apiKey = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';
$body = json_encode([
    'order_id' => 'T1',
    'amount' => 500000,
    'callback_url' => 'https://yoursite.com/payment/callback',
]);
$path = '/api/v1/transactions/create';
$ts = time();
$payload = $ts . "\nPOST\n" . $path . "\n" . $body;
$sig = hash_hmac('sha256', $payload, $secret);

// Headers: X-Api-Key, X-Timestamp, X-Signature