API documentation

Authentication (HMAC)

Every API request must include these headers:

• X-Api-Key — API key from the merchant panel
• X-Timestamp — Unix timestamp (max ±5 minutes drift)
• X-Signature — HMAC-SHA256 signature

Signature format:

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

For GET requests, body is an empty string. path includes the query string.

Create transaction

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": "Product purchase",
  "customer_mobile": "09123456789"
}

amount in Rials. callback_url required.

If order_id previously expired or failed, the transaction is renewed and a new gateway_url is returned. If still pending, the same link is returned. For a paid order you get 409. When payment time ends, the user is redirected to callback_url with status=expired.

Transaction status

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

Statuses: pending | paid | expired | failed

Successful payment callback

After SMS verification, a JSON POST is sent to callback_url.

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

Signature: remove the signature field, ksort + json_encode + HMAC-SHA256 with api_secret.

Incoming SMS (payment verification)

Forward transfer SMS from the merchant phone to our server. Authenticate with Device Token (from merchant panel).

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

{
  "token": "YOUR_DEVICE_TOKEN",
  "message": "Transfer of 1,000,127 Rials to card ..."
}

For iOS Shortcut, send token and message in JSON body. X-Device-Token header is also supported.

Success response (200):

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

No match (422): SMS received but no pending transaction matched that amount.

iOS Shortcut and Android guides: Merchant panel → SMS device → Guide (login required)

$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