اتصال ربات بله به زرینپال: قدمبهقدم با کد PHP (۱۴۰۵)
۱۵ خرداد ۱۴۰۵ - ۵ ژوئن ۲۰۲۶
بدون درگاه پرداخت، ربات فروشگاهی شما فقط یک ویترین است. در این مقاله، میخواهم دقیقاً به شما نشان دهم چطور با زبان PHP (که محبوبترین زبان برای رباتهای ایرانی است) ربات بله را به درگاه زرینپال متصل کنید. این راهنما یک مکمل عملی برای راهنمای جامع ساخت ربات فروشگاهی در بله است و پیشنیاز آن محسوب میشود. اگر مراحل را گامبهگام دنبال کنید، تا پایان این مقاله ربات شما قادر به دریافت وجه از مشتریان خواهد بود. من سعید شهبازی هستم و در خانه ربات و وب دهها پروژه از این دست را پیادهسازی کردهام، از جمله ربات کلینیک دکتر رضوانی که در بله فعال است و روزانه تراکنشهای موفقی دارد.
فرآیند اتصال ربات بله به زرینپال شامل ۴ مرحله اصلی است: ۱) دریافت کد مرچنت (Merchant ID) از زرینپال، ۲) ایجاد یک لینک پرداخت و ارسال آن به کاربر، ۳) مدیریت بازگشت (Callback) از زرینپال و ۴) ثبت تراکنش در دیتابیس و اطلاعرسانی به کاربر. در ادامه تمام این مراحل را با کد واقعی PHP پیاده میکنیم.
۱. پیشنیازها: مرچنت کد و کتابخانه زرینپال
اول از همه باید در سایت زرینپال ثبتنام کنید و پس از تأیید، یک Merchant ID (کد ۳۶ رقمی) دریافت کنید. این کد را در یک فایل `config.php` ذخیره میکنیم.
همچنین مطمئن شوید سرور شما SSL دارد (آدرس با `https://`). زرینپال فقط به آدرسهای امن callback میفرستد. اگر برای ربات بله از Webhook استفاده میکنید، این موضوع از قبل حل شده است.
۲. کد PHP: ایجاد درخواست پرداخت و ارسال لینک به کاربر
وقتی کاربر در ربات بله روی دکمه «پرداخت» کلیک میکند، ربات باید یک لینک پرداخت تولید کند و به او بدهد. کد زیر این کار را انجام میدهد:
<?php
// request_payment.php
require_once 'config.php'; // شامل $MERCHANT_ID
// اطلاعات سفارش (از دیتابیس یا سشن ربات)
$amount = 250000; // مبلغ به ریال
$order_id = 1024; // شماره سفارش
$callback_url = "https://yourdomain.com/verify_payment.php";
// پارامترهای ارسالی به زرینپال
$data = [
'merchant_id' => $MERCHANT_ID,
'amount' => $amount,
'callback_url' => $callback_url,
'description' => "سفارش شماره $order_id",
'metadata' => ['order_id' => $order_id]
];
$ch = curl_init('https://api.zarinpal.com/pg/v4/payment/request.json');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
if ($result['data']['code'] == 100) {
// ذخیره authority در دیتابیس
$authority = $result['data']['authority'];
$payment_url = "https://www.zarinpal.com/pg/StartPay/" . $authority;
// ارسال لینک پرداخت به کاربر در بله
sendMessage($chat_id, "برای پرداخت روی لینک زیر کلیک کنید:\n$payment_url");
} else {
sendMessage($chat_id, "خطا در اتصال به درگاه. لطفاً دوباره تلاش کنید.");
}
?>
تابع `sendMessage` همان تابع ارسال پیام در API بله است که در هاب اصلی توضیح دادیم. نکته مهم: مبلغ باید به ریال وارد شود (تومان × ۱۰).
۳. مدیریت Callback و تأیید پرداخت
بعد از اینکه کاربر پرداخت را انجام داد، زرینپال او را به `callback_url` که تعیین کردهاید برمیگرداند. حالا باید اعتبار تراکنش را بررسی کنید:
<?php
// verify_payment.php
require_once 'config.php';
$authority = $_GET['Authority'];
$status = $_GET['Status'];
if ($status == 'OK') {
// دریافت اطلاعات تراکنش از دیتابیس
$order = getOrderByAuthority($authority); // تابع کمکی
$amount = $order['amount'];
$data = [
'merchant_id' => $MERCHANT_ID,
'amount' => $amount,
'authority' => $authority
];
$ch = curl_init('https://api.zarinpal.com/pg/v4/payment/verify.json');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
if ($result['data']['code'] == 100) {
// پرداخت موفق
$ref_id = $result['data']['ref_id'];
updateOrderStatus($order['id'], 'paid', $ref_id);
sendMessage($order['chat_id'], "✅ پرداخت شما با موفقیت انجام شد.\nکد پیگیری: $ref_id");
} else {
// پرداخت ناموفق
sendMessage($order['chat_id'], "❌ پرداخت تأیید نشد. لطفاً مجدداً تلاش کنید.");
}
} else {
sendMessage($order['chat_id'], "پرداخت توسط کاربر کنسل شد.");
}
?>
اگر `code` برابر ۱۰۰ بود، یعنی پرداخت موفق بوده. سپس باید سفارش را در دیتابیس به وضعیت «پرداخت شده» تغییر دهید و پیام تأیید همراه با کد رهگیری زرینپال (`ref_id`) به کاربر ارسال کنید.
۴. نکات امنیتی حیاتی
- هرگز `MERCHANT_ID` را در کد کلاینت قرار ندهید. آن را در فایل `config.php` خارج از پوشه public نگه دارید.
- همیشه در callback، `authority` را با دیتابیس چک کنید تا از حملات تزریقی جلوگیری شود.
- مبلغ تراکنش را از دیتابیس بخوانید، نه از پارامترهای GET. (چون کاربر میتواند مبلغ را دستکاری کند).
- برای جلوگیری از SQL Injection، همیشه از Prepared Statements در PDO استفاده کنید.
برای امنیت کامل ربات فروشگاهی، مقاله امنیت ربات فروشگاهی بله را حتماً مطالعه کنید.
۵. خطاهای رایج و رفع آنها
| خطا | علت | راهحل |
|---|---|---|
| کد ۱۰۱ (تراکنش تکراری) | پرداخت قبلاً تأیید شده | بررسی وضعیت سفارش قبل از verify |
| عدم بازگشت به callback | آدرس callback اشتباه یا SSL نامعتبر | چک کردن https و آدرس کامل |
| خطای CURL | محدودیت سرور یا فیلترینگ | تنظیم CURLOPT_SSL_VERIFYPEER و استفاده از Proxy در صورت نیاز |
۶. جمعبندی: حالا ربات شما یک فروشگاه واقعی است
با انجام این مراحل، ربات بله شما اکنون میتواند از کاربران پول دریافت کند. این همان نقطهای است که یک ربات از «سرگرمی» به «کسبوکار» تبدیل میشود. اگر این کدها را روی پروژه خود پیاده کنید و به مشکل خوردید، تیم خانه ربات و وب آماده کمک به شماست. ما در پروژه کلینیک دکتر رضوانی دقیقاً از همین ساختار استفاده کردیم و روزانه دهها تراکنش موفق داریم.
برای قدمهای بعدی، پیشنهاد میکنم مدیریت محصولات و موجودی را یاد بگیرید تا فروشگاهتان حرفهایتر شود.
۷. سوالات متداول
آیا میتوانم از درگاههای دیگر مثل نکست پی استفاده کنم؟
بله، ساختار کلی شبیه زرینپال است. فقط آدرس API و پارامترها تفاوت میکند. اگر نیاز به پیادهسازی اختصاصی دارید، با ما تماس بگیرید.
آیا کاربران بله به لینکهای پرداخت اعتماد میکنند؟
بله، چون لینک مستقیماً به `zarinpal.com` باز میشود و کاربر آدرس را میبیند. همچنین ارسال پیام تأیید پس از پرداخت، اعتماد را افزایش میدهد.
هزینه تراکنش در زرینپال چقدر است؟
بسته به طرح زرینپال، معمولاً بین ۱ تا ۳ درصد مبلغ تراکنش. برای کسبوکارهای کوچک رایگان یا بسیار کم است.
اگر کاربر بعد از پرداخت بسته شود، چطور مطلع شوم؟
زرینپال callback را به سرور شما میفرستد حتی اگر کاربر مرورگر را ببندد. به همین دلیل ثبت سفارش در دیتابیس قبل از ارسال به درگاه حیاتی است.
آیا این کد برای تلگرام هم کار میکند؟
بله، دقیقاً همین کد برای تلگرام هم قابل استفاده است. فقط بخش ارسال پیام (`sendMessage`) متناسب با API تلگرام تغییر میکند. برای راهنمایی کامل، راهنمای جامع ربات بله را ببینید.
💬 نظرات کاربران
هنوز نظری ثبت نشده است. اولین نفری باشید که نظر میدهید!