پرش به محتوای اصلی
واریزت
مستندات توسعه‌دهندگان

API عمومی واریزت،
بدون ثبت‌نام و بدون پلن پولی.

یک درخواست برای ساخت سفارش، یک وب‌هوک امضاشده برای تایید. با کلید تست، همه سناریوها را در Sandbox و بدون پول واقعی امتحان کنید.

https://api.varizet.ir/v1نسخه 2026-10-01OpenAPI 3.1
ساخت سفارش با مبلغ یکتا
# create an order with a unique amount
curl -X POST https://api.varizet.ir/v1/orders \
  -H "Authorization: Bearer vz_test_4eC39HqLyjWDarjt" \
  -H "Idempotency-Key: ketabnama-order-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 8500000,
    "merchant_order_id": "INV-12345",
    "unique_mode": "increase",
    "customer": { "phone": "09121234567" },
    "return_url": "https://ketabnama.ir/checkout/thanks?o=12345"
  }'

# 201 Created
{
  "id": "ord_01JBX4Q8M6",
  "code": "VZ-8K2Q",
  "status": "awaiting_payment",
  "unique_amount": 8500430,
  "expires_at": "2026-10-28T11:02:00Z",
  "payment_url": "https://pay.varizet.ir/p/kJ8s2QaX7mZr4TnB"
}

شروع سریع

اولین سفارش را در پنج دقیقه بسازید. همه نمونه‌ها با کلید تست اجرا می‌شوند و هیچ پول واقعی جابه‌جا نمی‌شود.

  1. ۱

    کلید تست بگیرید

    رایگان ثبت‌نام کنید؛ کلید vz_test_… بلافاصله در پنل، بخش کلیدهای API آماده است. کلید را فقط سمت سرور نگه دارید.
  2. ۲

    سفارش با مبلغ یکتا بسازید

    مبلغ را به ریال و یک Idempotency-Key یکتا بفرستید. پاسخ شامل unique_amount و payment_url است.

    curl https://api.varizet.ir/v1/orders \
      -H "Authorization: Bearer vz_test_4eC39HqLyjWDarjt" \
      -H "Idempotency-Key: 5c1f0d7e-order-12345" \
      -H "Content-Type: application/json" \
      -d '{"amount": 8500000, "merchant_order_id": "INV-12345"}'
  3. ۳

    مشتری را به صفحه پرداخت بفرستید

    مشتری را به payment_url هدایت کنید یا مبلغ یکتا و کارت مقصد را در صفحه خودتان نمایش دهید. پس از تایید، مشتری به return_url برمی‌گردد.
  4. ۴

    وب‌هوک order.paid را تایید کنید

    امضای Varizet-Signature را بررسی کنید و سفارش را پرداخت‌شده علامت بزنید. جزئیات در بخش تایید امضا.

اصول API

API به سبک APIهای پرداخت شناخته‌شده طراحی شده است؛ اگر با یکی کار کرده باشید، این یکی هم آشناست.

آدرس پایه
https://api.varizet.ir/v1
احراز هویت
Authorization: Bearer <key> با کلیدهای vz_live_… و vz_test_…
قالب
JSON و UTF-8؛ زمان‌ها ISO-8601 به UTC؛ مبالغ عدد صحیح ریال
Idempotency
هدر Idempotency-Key برای همه POSTها، نگهداری ۲۴ ساعت؛ تکرار با بدنه متفاوت ← 409 idempotency_mismatch
صفحه‌بندی
Cursor: ?limit=50&starting_after=ord_… ← { data, has_more, next_cursor }
نسخه
در مسیر (/v1)؛ تغییرات جزئی با هدر Varizet-Version: 2026-10-01
سقف درخواست
رایگان ۶۰، رشد ۳۰۰، حرفه‌ای ۱٬۲۰۰ در دقیقه؛ هدرهای RateLimit-*
شناسه‌ها
پیشوندی: ord_، plink_، cus_، dep_، ref_، whe_، evt_

وب‌هوک‌ها

چند endpoint با رویدادهای دلخواه بسازید. هر تحویل امضا می‌شود، لاگ کامل دارد و از پنل یا API دوباره فرستاده می‌شود.

رویدادهای وب‌هوک
رویدادزمان ارسال
order.createdساخت سفارش
order.paidتایید پرداخت، خودکار یا دستی
order.needs_reviewورود سفارش به صندوق بررسی
order.underpaidکم‌واریز؛ مابه‌التفاوت با مبلغ یکتای جدید درخواست می‌شود
order.expiredپایان مهلت تکمیلی بدون پرداخت
order.canceledلغو سفارش توسط فروشنده یا API
refund.createdثبت بازپرداخت
deposit.unmatchedواریزی که به هیچ سفارشی نرسید
device.offlineقطع شدن دستگاه یا کانال تشخیص
device.onlineبرگشت دستگاه به حالت آنلاین
card.cap_reachedرسیدن کارت مقصد به سقف روزانه
نمونه تحویل order.paid
# POST https://ketabnama.ir/webhooks/varizet
Varizet-Signature: t=1761647652,v1=5257a869e7ec…8bd
Content-Type: application/json

{
  "id": "evt_01JBX5R2T9",
  "type": "order.paid",
  "created_at": "2026-10-28T10:34:12Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "ord_01JBX4Q8M6",
      "code": "VZ-8K2Q",
      "status": "paid",
      "unique_amount": 8500430,
      "paid_amount": 8500430,
      "merchant_order_id": "INV-12345",
      "match": { "score": 98, "channel": "android_sms" }
    }
  }
}
  • پاسخ 2xx در کمتر از ۱۰ ثانیه یعنی تحویل موفق.
  • تلاش مجدد نمایی، ۸ بار: ۱۰ ثانیه، ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه، ۲ ساعت، ۶ ساعت، ۱۲ ساعت، ۲۴ ساعت.
  • اگر همه تحویل‌های یک endpoint سه روز پیاپی شکست بخورد، غیرفعال و به شما اعلان می‌شود.
  • ترتیب تضمین نمی‌شود؛ از created_at و GET /v1/orders/{id} استفاده کنید.

تایید امضای وب‌هوک

هر درخواست هدر Varizet-Signature دارد: زمان ارسال و HMAC-SHA256 روی «زمان + نقطه + بدنه خام» با secret همان endpoint. امضا زمان‌دار است تا درخواست قدیمی دوباره پخش نشود.

الگوریتم
Varizet-Signature: t=1761647652,v1=5257a869e7…

signed_payload = t + "." + raw_body
expected = HMAC_SHA256(endpoint_secret, signed_payload)  # hex
accept if constant_time_equal(expected, v1) and |now - t| <= 300s
import crypto from 'node:crypto';

// rawBody: the exact request body string, before JSON.parse
export function verifyVarizetSignature(rawBody, header, secret) {
  const parts = header.split(',').map((p) => p.trim().split('='));
  const t = Number(parts.find(([k]) => k === 't')?.[1]);
  // during secret rotation the header carries two v1 values
  const signatures = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - t) <= 300;
  return fresh && signatures.some((v1) =>
    v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected)));
}
بدنه خام

امضا را روی بدنه دقیقاً همان‌طور که رسیده بسازید، پیش از parse کردن JSON.

پنجره ۵ دقیقه

درخواستی که t آن بیش از ۳۰۰ ثانیه با زمان سرور شما فاصله دارد رد شود.

چرخش secret

تا ۲۴ ساعت پس از چرخش، هدر دو مقدار v1 دارد؛ پذیرش هر کدام کافی است.

Sandbox و تست

هر درخواستی با کلید vz_test_ در محیطی کاملاً جدا اجرا می‌شود: سفارش، لینک و وب‌هوک واقعی، با واریز شبیه‌سازی‌شده که از همان موتور تطبیق عبور می‌کند.

شبیه‌سازی واریز
# test keys only: simulate a deposit for an awaiting order
curl -X POST https://api.varizet.ir/v1/test/deposits \
  -H "Authorization: Bearer vz_test_4eC39HqLyjWDarjt" \
  -H "Idempotency-Key: sim-12345-1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 8500430, "payer_last4": "7890", "bank": "mellat"}'

# → matched to VZ-8K2Q, and order.paid is delivered to your endpoint
  • POST /v1/test/deposits واریز را با مبلغ، بانک و ۴ رقم کارت دلخواه شبیه‌سازی می‌کند.
  • POST /v1/test/orders/{id}/expire سفارش را فوراً منقضی می‌کند تا مسیر انقضا را تست کنید.
  • پاسخ‌ها "livemode": false دارند و در سقف تراکنش ماهانه حساب نمی‌شوند.
سه کارت مجازی در هر حساب تست
  • ملت6104 3378 9012 4520
  • سامان6219 8610 3452 9015
  • ملی6037 9910 1234 5678

خطاها

همه خطاها یک قالب دارند؛ type برای دسته‌بندی، code برای منطق برنامه و message فارسی برای نمایش به کاربر.

قالب خطا
{
  "error": {
    "type": "invalid_request",
    "code": "amount_too_small",
    "message": "حداقل مبلغ سفارش ۱۰٬۰۰۰ ریال است.",
    "param": "amount",
    "request_id": "req_01JBX4Q8M6"
  }
}
کدهای خطای API
HTTPtypeنمونه code
400invalid_requestamount_too_small, invalid_phone, invalid_callback_url
401authentication_errorinvalid_api_key, key_revoked
403permission_errorscope_missing, ip_not_allowed, plan_limit_reached
404not_foundorder_not_found
409conflictunique_amount_exhausted, idempotency_mismatch, order_not_cancelable
422validation_errormerchant_order_id_duplicate
429rate_limitedtoo_many_requests
5xxapi_errorinternal_error (با request_id به پشتیبانی بدهید)

SDK و ابزارها

کلاینت‌های رسمی تایید امضا و مدل‌های تایپ‌شده را آماده دارند. برای هر زبان دیگری، از مرجع OpenAPI کلاینت بسازید.

  • موجود

    Node.js SDK

    TypeScript با تایپ کامل تولیدشده از OpenAPI و کمک‌کننده وب‌هوک برای Express، Fastify و Next.js.

    npm i @varizet/nodeشروع سریع
  • موجود

    OpenAPI و Postman

    مرجع ماشینی کامل API عمومی برای تولید کلاینت در هر زبان و مجموعه Postman آماده.

    دریافت openapi.json
  • موجود

    PHP SDK

    کلاینت API، تایید امضای وب‌هوک و مدل‌های تایپ‌شده؛ هسته مشترک همه افزونه‌های PHP.

    composer require varizet/varizet-phpنمونه کد PHP
  • موجود

    لاراول

    Facade، کانفیگ، مسیر وب‌هوک با Middleware امضا و رویدادهای لاراول مثل OrderPaid.

    composer require varizet/laravelشروع سریع
  • موجود

    Python SDK

    کلاینت sync و async با کمک‌کننده‌های Django و FastAPI.

    pip install varizetSDKها و ابزارها
  • موجود

    Varizet CLI

    وب‌هوک‌ها را به لوکال‌هاست بیاورید، رویداد آزمایشی بسازید و واریز شبیه‌سازی کنید.

    varizet listen --forward-to localhost:3000/webhooksSandbox و تست
Varizet CLI
varizet login
varizet listen --forward-to localhost:3000/webhooks
varizet trigger order.paid
varizet simulate deposit 8500430

کلید تست را بگیرید و اولین سفارش را بسازید.

بدون پلن پولی و بدون کارت بانکی؛ Sandbox در پلن رایگان هم کامل است و API Live از پلن رشد فعال می‌شود.