پرش به محتوای اصلی

راهنمای توسعه‌دهندگان

سه کار: پرداخت بسازید، مشتری را به صفحه پرداخت بفرستید و وقتی خبر رسید، سمت سرور verify کنید.

۱. کلید API

پس از تأیید حساب، در پنل برای فروشگاه خود کلید می‌سازید. کلید sk_test_… برای محیط آزمایشی و sk_live_… برای پرداخت واقعی است. کلید را فقط سمت سرور نگه دارید و هیچ‌وقت در مرورگر قرار ندهید. نشانی API: https://api.varizpardaz.com

۲. ساخت پرداخت

مبلغ به ریال و عدد صحیح است. فقط amount و order_id الزامی است. هدر Idempotency-Key از ساخت تکراری جلوگیری می‌کند.

curl -X POST https://api.varizpardaz.com/v1/payments   -H "Authorization: Bearer sk_test_..."   -H "Content-Type: application/json"   -H "Idempotency-Key: order-A-1042"   -d '{
    "amount": 5000000,
    "order_id": "A-1042",
    "callback_url": "https://shop.example.com/pay/callback",
    "return_url": "https://shop.example.com/orders/A-1042"
  }'

پاسخ شامل payment_url است؛ مشتری را به آن نشانی بفرستید. مبلغی که مشتری باید واریز کند در payable_amount است و با مبلغ سفارش چند تومان فرق دارد.

۳. وب‌هوک

پس از تأیید، یک درخواست POST با بدنه JSON به نشانی وب‌هوک شما می‌آید. هدر X-Signature به شکل t=…,v1=… است و v1 برابر HMAC-SHA256 رشته "{t}." + body با رمز وب‌هوک شماست. بدنه خام را بررسی کنید، نه نسخه دوباره‌سریال‌شده را.

import { createHmac, timingSafeEqual } from 'node:crypto';

// X-Signature: t=<unix seconds>,v1=<hex>
function verifySignature(secret, header, rawBody, now = Date.now() / 1000) {
  const parts = header.split(',').map((p) => p.trim());
  const t = parts.find((p) => p.startsWith('t='))?.slice(2);
  if (!t || Math.abs(now - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(t + '.').update(rawBody).digest();
  return parts
    .filter((p) => p.startsWith('v1='))
    .some((p) => /^[0-9a-f]{64}$/i.test(p.slice(3)) &&
      timingSafeEqual(Buffer.from(p.slice(3), 'hex'), expected));
}

شناسه رویداد (id) در هر تلاش مجدد یکسان است؛ رویدادهای تکراری را نادیده بگیرید.

۴. verify سمت سرور

وب‌هوک و بازگشت مرورگر مشتری فقط خبر می‌دهند و اثبات پرداخت نیستند. کالا را فقط وقتی تحویل دهید که پاسخ verify وضعیت paid یا paid_late و first_verification: true داشته باشد.

curl -X POST https://api.varizpardaz.com/v1/payments/pay_.../verify   -H "Authorization: Bearer sk_test_..."

# Deliver only if: status is "paid" or "paid_late" AND first_verification is true

لینک پرداخت و ربات تلگرام

فروشگاه‌ساز یا سایت لازم نیست. با POST /v1/links برای هر سفارش یک لینک پرداخت بسازید و برای مشتری بفرستید (در پنل هم همین کار را بدون کد می‌شود کرد). فیلد metadata هر چیزی را که لازم دارید، مثل شناسه چت تلگرام و محصول، در هر خواندن و وب‌هوک و رویداد برمی‌گرداند.

curl -X POST https://api.varizpardaz.com/v1/links 
  -H "Authorization: Bearer sk_test_..." 
  -H "Content-Type: application/json" 
  -d '{
    "amount": 1500000,
    "title": "اشتراک یک‌ماهه",
    "metadata": { "chat_id": 123456, "sku": "vpn-1m" },
    "external_ref": "tg-123456-vpn-1m-1"
  }'

اگر ربات شما آدرس عمومی ندارد، به‌جای وب‌هوک از GET /v1/events استفاده کنید؛ رویدادها هفت روز نگه داشته می‌شوند و با cursor دقیقاً از جایی که ماندید ادامه می‌دهید. تحویل کالا فقط وقتی که verified برابر true است.

# بدون آدرس عمومی: رویدادها را خودتان بپرسید و cursor را نگه دارید
curl "https://api.varizpardaz.com/v1/events?after=ev1_120" 
  -H "Authorization: Bearer sk_test_..."

# سپس برای هر payment.paid، پرداخت را بخوانید و فقط اگر verified: true بود تحویل دهید
curl https://api.varizpardaz.com/v1/payments/pay_... -H "Authorization: Bearer sk_test_..."

راهنمای کامل فارسی، دو ربات نمونهٔ آماده (Node با grammY و Python با aiogram) و فهرست امنیتی در مخزن پروژه، فایل‌های docs/bots.md و examples/، هست.

راهنمای گام‌به‌گام برای ربات‌نویس‌ها در صفحه ربات تلگرام و توضیح لینک‌ها برای صاحب فروشگاه در لینک پرداخت است.

محیط آزمایشی

با کلید sk_test_… می‌توانید واریز را شبیه‌سازی کنید و همان تطبیق، وب‌هوک و صفحه پرداخت را بدون پول واقعی ببینید. داده آزمایشی و واقعی کاملاً جداست و پرداخت آزمایشی کارمزد ندارد (وب‌هوک آن livemode: false دارد).

curl -X POST https://api.varizpardaz.com/v1/test/deposits 
  -H "Authorization: Bearer sk_test_..." 
  -H "Content-Type: application/json" 
  -d '{ "payment_id": "pay_..." }'

نیاز به راهنمایی بیشتر دارید؟ از صفحه تماس برایمان بنویسید.

کلید آزمایشی بگیرید

پس از ثبت‌نام و تأیید حساب، در پنل کلید API می‌سازید.