یک درخواست برای ساخت لینک،
یک وب‌هوک برای تایید پرداخت

گردش کار

برای هر سفارش یک لینک پرداخت می‌سازید و به خریدار می‌دهید. خریدار همان مبلغ را کارت‌به‌کارت واریز می‌کند. سیستم واریزی بانکی را تشخیص می‌دهد و بلافاصله یک وب‌هوک درباره موفقیت پرداخت به آدرس callback شما ارسال می‌کند؛ بدون رسید، بدون تایید دستی.

احراز هویت

از پنل کاربری ← پروفایل ← کلید API یک کلید بسازید. کلید فقط همان لحظه نمایش داده می‌شود، آن را ذخیره کنید. هر درخواست باید آن را در هدر Authorization بفرستد:

Authorization: Bearer YOUR_API_KEY

کلید معادل رمز حساب شماست؛ فقط سمت سرور نگه‌داری شود، هرگز در کد سمت کاربر قرار نگیرد.

پیش‌نیاز: باید یک بار آدرس callback_url را در پروفایل خود ثبت کرده باشید، وگرنه با خطای 422 مواجه می‌شوید.

توصیه میشود expires_at را بیشتر از یک ساعت وارد نکنید.

curl -X POST https://variza.ir/api/v1/pay \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "amount": 500000,
        "return_url": "https://example.com/callback",
        "title": "Order #123",
        "expires_in": "1h",
        "card_last_4": "random",
        "member_phone": "09123456789"
    }'

{
    "slug": "aB3xY9...",
    "pay_url": "https://variza.ir/pay/aB3xY9...",
    "amount": 500000,
    "title": "Order #123",
    "return_url": "https://example.com/callback",
    "expires_at": "2026-08-05T12:00:00+00:00"
}

pay_url لینکی است که باید خریدار را به آن ریدایرکت کنید.

مارکت‌پلیس

اگر اشتراک مارکت‌پلیس دارید، می‌توانید لینک را به نام یکی از اعضای تیم بسازید. کافیست member_phone را در درخواست ارسال کنید. لینک برای حساب آن عضو و با کارت‌های خودش ساخته می‌شود، اما callback_url و امضای وب‌هوک همچنان از مالک مارکت‌پلیس استفاده می‌شود و مقدار member_phone در بدنه وب‌هوک برمی‌گردد تا سفارش را به نماینده مربوطه نسبت دهید.

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

وب‌هوک پرداخت

به‌محض موفقیت پرداخت، رویداد payment.paid با متد POST به callback_url ثبت‌شده در پروفایل شما ارسال می‌شود.

{
    "event": "payment.paid",
    "slug": "aB3xY9...",
    "attempt_code": "152688947983",
    "amount": 500128,
    "base_amount": 500000,
    "status": "paid",
    "sent_at": "2026-08-05T11:45:00+00:00",
    "member_phone": "09123456789" // or null
}

در حالت مارکت‌پلیس فیلد member_phone نیز در بدنه ارسال می‌شود (در غیر این صورت null).

امضا با کلید webhook_secret شما و روی بدنه خام دریافتی محاسبه می‌شود:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (! hash_equals($expected, $signature)) {
    http_response_code(400);
    exit;
}

برای تایید دریافت با HTTP 200 پاسخ دهید. در غیر این صورت، ارسال با فاصله‌های ۳۰ ثانیه تا ۱۰ دقیقه، حداکثر ۵ بار تکرار می‌شود.

کدهای خطا

SDK‌های رسمی

برای اتصال سریع‌تر و مطمئن‌تر، کتابخانه‌های رسمی را به‌جای درخواست‌های دستی استفاده کنید. هر SDK ساخت لینک پرداخت و تایید امضای وب‌هوک را به‌صورت آماده و تست‌شده در اختیار شما قرار می‌دهد.

WooCommerce variza-woocommerce-plugin

افزونه‌ی رسمی ووکامرس؛ فقط نصب و تنظیم کنید — بدون نیاز به کدنویسی. پرداخت کارت‌به‌کارت با تأیید کاملاً خودکار سفارش، صفحه‌ی تنظیمات فارسی و پشتیبانی از ووکامرس ۷.۰ به بالا.

GitHub افزونه ووکامرس

Laravel variza-laravel

پکیج رسمی لاراول برای ساخت لینک پرداخت و مدیریت وب‌هوک — با Facade، Event و Middleware آماده، کاملاً یکپارچه با اکوسیستم لاراول.

GitHub Composer

PHP variza-php-sdk

کتابخانه رسمی PHP برای ساخت لینک پرداخت و تایید وب‌هوک — با مستندات کامل، تست واحد و پشتیبانی از PHP 8.1 به بالا.

GitHub Composer

Node.js variza-node-sdk

کتابخانه رسمی Node.js برای ساخت لینک پرداخت و تایید وب‌هوک — بدون وابستگی، با تعریف کامل تایپ‌ها و پشتیبانی از Node.js 18 به بالا.

GitHub npm