راهنمای توسعهدهندگان
سه کار: پرداخت بسازید، مشتری را به صفحه پرداخت بفرستید و وقتی خبر رسید، سمت سرور 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_..." }'نیاز به راهنمایی بیشتر دارید؟ از صفحه تماس برایمان بنویسید.