راه‌اندازی پرداخت روی سایت چیز پیچیده‌ای نیست؛ در واقع سه کار اصلی دارد: ساخت تراکنش، فرستادن مشتری به صفحه‌ی پرداخت و نهایی کردن سفارش بعد از تایید. در این راهنما نشان می‌دهیم اتصال درگاه کارت به کارت به سایت چگونه انجام می‌شود؛ چه برنامه‌نویس باشید و چه نه.
پیش‌نیازها
- ثبت‌نام و ساخت یک پروژه در پنل.
- افزودن کارت بانکی و نصب اپ اندروید (راهنمای امنیت اپ).
- ساخت کلید API از بخش «اتصال و API» و ثبت آدرس کالبک.
گام ۱: ساخت تراکنش
از سرور سایت خود (نه مرورگر مشتری) یک درخواست POST به /api/v1/transactions بفرستید. هدر X-API-Key کلید شماست و بدنه JSON است: مبلغ به ریال، شماره سفارش، توضیح، آدرس کالبک و آدرس بازگشت.
curl -X POST https://YOUR-DOMAIN/api/v1/transactions \
-H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"amount":3000000,"order_id":"1001","callback_url":"https://shop.com/callback","return_url":"https://shop.com/thanks"}'
پاسخ شامل transaction_id، مبلغ نهایی (با رقم یکتا) و pay_url است. مشتری را به pay_url هدایت کنید.
گام ۲: دریافت کالبک و اعتبارسنجی امضا
پس از پرداخت، یک POST به آدرس کالبک می‌آید. هدر X-Signature مقدار HMAC-SHA256 بدنه‌ی خام با «کلید امضای» پروژه است. حتماً با مقایسه‌ی زمان‌ثابت اعتبارسنجی کنید:
<?php
$raw = file_get_contents('php://input');
$sig = hash_hmac('sha256', $raw, 'WEBHOOK_SECRET');
if (!hash_equals($sig, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) { http_response_code(403); exit; }
$d = json_decode($raw, true);
if ($d['status'] === 'paid') { /* سفارش $d['order_id'] را نهایی کنید */ }
http_response_code(200);
گام ۳: بررسی وضعیت (اختیاری ولی توصیه‌شده)
برای اطمینان بیشتر، پیش از تحویل کالا یک‌بار وضعیت را با GET /api/v1/transactions/{id} بخوانید. وضعیت‌ها: pending، paid، expired، canceled. این کار از اشتباه در اثر کالبک تکراری یا تاخیری جلوگیری می‌کند.
نکات مهم پیاده‌سازی
- idempotent باشید: کالبک ممکن است دوبار برسد؛ سفارشِ قبلاً نهایی‌شده را دوباره پردازش نکنید.
- کلید API را در سرور نگه دارید و هرگز داخل جاوااسکریپت سمت مرورگر نگذارید.
- مبلغ ریال است. اگر قیمت‌های سایت تومان است، ۱۰ برابر کنید.
- آدرس کالبک عمومی باشد: آدرس‌های داخلی (localhost یا IP خصوصی) پذیرفته نمی‌شوند.
- برای تست از «ارسال تست» پنل و پروژه‌ی آزمایشی استفاده کنید.
وردپرس و ووکامرس
اگر سایت وردپرسی دارید، دو راه عملی وجود دارد: ۱) استفاده از یک افزونه‌ی درگاه سفارشی که همین API را صدا بزند؛ ۲) یک قطعه کد کوچک در functions.php یا افزونه‌ی اختصاصی که هنگام ثبت سفارش، تراکنش بسازد و کالبک را به یک endpoint وردپرس (مثلاً با REST API) بدهد. منطق هر دو یکی است: ساخت تراکنش ← هدایت به pay_url ← کالبک ← تغییر وضعیت سفارش به «در حال انجام».
سایت‌های Node.js و Python
نمونه‌کدهای آماده‌ی Node.js (Express) و Python (Flask) در بخش مستندات پنل، همراه با نمونه‌ی پاسخ و خطاها موجود است؛ می‌توانید با یک کلیک کپی کنید.
خطاهای متداول
kyc_required: ابتدا احراز هویت باید تایید شود.no_active_card: حداقل یک کارت فعال اضافه کنید.credit_exhausted: اشتراک یا اعتبار کیف پول تمام شده است.invalid_callback: آدرس کالبک باید عمومی و معتبر باشد.
نمونه‌ی ساده در Node.js
اگر سایت شما با Node.js است، فقط کافی است یک تابع برای ساخت تراکنش و یک مسیر برای کالبک بنویسید. در ساخت تراکنش، مبلغ را به ریال بفرستید و pay_url را به کاربر برگردانید. در مسیر کالبک، بدنه‌ی خام را بخوانید، امضا را اعتبارسنجی کنید و بعد وضعیت سفارش را عوض کنید. نکته‌ی مهم این است که بدنه را قبل از تبدیل به JSON و به‌صورت خام برای محاسبه‌ی امضا نگه دارید؛ چون هر تغییر کوچک در فاصله یا ترتیب کلیدها امضا را به‌هم می‌ریزد.
چطور آن را تست کنیم؟
- پروژه‌ی آزمایشی بسازید و کلید API آن را بگیرید.
- یک تراکنش بسازید و روی
pay_urlبروید؛ در پروژه‌ی آزمایشی می‌توانید پرداخت را شبیه‌سازی کنید. - در بخش کالبک پنل «ارسال تست» را بزنید و پاسخ 200 را بررسی کنید.
- لاگ‌های «آخرین ارسال‌ها» را ببینید تا اگر خطایی بود، کد وضعیت و زمان پاسخ را بدانید.
چه زمانی نیاز به کمک دارید؟
اگر کدنویسی بلد نیستید، می‌توانید از لینک پرداخت دستی استفاده کنید یا از یک برنامه‌نویس بخواهید فقط همین دو بخش (ساخت تراکنش و کالبک) را بنویسد؛ معمولاً کمتر از یک روز کار است. مستندات داخل پنل نمونه‌کدهای کامل cURL، PHP، Node.js و Python دارد.
اگر گیر کردید
اتصال کارت به کارت خودکار به سایت، معمولاً در یک بعدازظهر انجام می‌شود. اگر هنوز نماد اعتماد ندارید، مشکلی نیست؛ مقاله‌ی درگاه پرداخت بدون اینماد را ببینید و همین حالا شروع کنید.