مستندات API

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

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

X-Api-Key — کلید API از پنل merchant
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 (تأیید پرداخت)

برای forward کردن SMS واریز از گوشی merchant به سرور. احراز هویت با Device Token (از پنل merchant).

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 و اندروید: پنل merchant → دستگاه SMS → راهنما (نیاز به ورود)

نمونه PHP

$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