آموزش اتصال درگاه پرداخت به ربات بله

بله پیام‌رسانی است که بسیاری از کسب‌وکارها برای فروش، ارائهٔ آموزش و تحویل اشتراک از آن استفاده می‌کنند. اگر ربات شما در بله فعال است و می‌خواهید پرداخت را همان‌جا بگیرید، می‌توانید از بات آمادهٔ پی‌اکسا در بله استفاده کنید و لازم نیست خودتان رابط پرداخت بسازید. این آموزش مسیر را از ساخت پرداخت تا تحویل سفارش توضیح می‌دهد.

روش کار به‌طور خلاصه

سرور شما یک پرداخت می‌سازد. در پاسخ، پی‌اکسا لینک آمادهٔ بات خودش را در بله برمی‌گرداند. شما آن را به مشتری می‌دهید و او وارد بات پی‌اکسا می‌شود. آنجا شمارهٔ کارت، نام دارنده، مبلغ دقیق، مهلت و شمارهٔ سفارش شما را می‌بیند. بعد از واریز، پیام بله به‌صورت خودکار به «موفق» تغییر می‌کند و مشتری با دکمهٔ «بازگشت به پذیرنده» به ربات شما برمی‌گردد.

پیش از شروع

• حساب پذیرندهٔ فعال و کلید API. مراحل ثبت‌نام را در راهنمای فعال‌سازی ببینید.
• ربات بلهٔ شما و دامنهٔ سرورش باید در صفحهٔ «درخواست درگاه پرداخت» پنل ثبت و تأیید شده باشند.
• کلید API باید فقط روی سرور شما نگه داشته شود.

گام اول: ساخت پرداخت

curl -X POST "https://pay.pexn.ir/v2/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "order_id": "BALE-88-1024",
    "return_url": "https://ble.ir/YourBot",
    "callback_url": "https://your-bot-server.example.com/payexa/callback"
  }'

مبلغ به ریال است. لینک ربات بلهٔ خودتان را در return_url بگذارید. اگر ربات شما وب‌سرور دارد، callback_url را هم روی دامنهٔ همان سرور بدهید تا اعلان امضاشده دریافت کنید.

پاسخ موفق (کد ۲۰۱) به این شکل است:

{
  "ok": true,
  "data": {
    "payment_id": "A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    "order_id": "BALE-88-1024",
    "status": "pending",
    "bale_url": "https://ble.ir/payexa_bot?start=pay_A7F3...",
    "payment_url": "/payment/start?authority=A7F3..."
  }
}

لینک bale_url را به مشتری بدهید و فقط payment_id را کنار سفارش نگه دارید. اگر بات بلهٔ پی‌اکسا در دسترس نباشد، bale_url برابر null می‌شود؛ در این حالت payment_url را بدهید که داخل بله هم باز می‌شود.

گام دوم: چه چیزی به مشتری نشان داده می‌شود؟

این بخش خودکار است و پیاده‌سازی نمی‌خواهد، اما برای پاسخ‌گویی به مشتری لازم است بدانید:

• پیام اول، مبلغ دقیق قابل واریز را همراه با شمارهٔ کارت و نام دارنده نشان می‌دهد و مهلت پرداخت را اعلام می‌کند.
• مشتری بعد از واریز می‌تواند دکمهٔ «بررسی پرداخت» را بزند. نتیجه همان لحظه در پیام به‌روز می‌شود.
• حتی اگر مشتری دکمه را نزند، بررسی خودکار هر چند ثانیه انجام می‌شود و به‌محض تأیید پیامکی واریز، پیام به حالت موفق می‌رود.

گام سوم: برگشت به ربات شما و تأیید

وقتی مشتری «بازگشت به پذیرنده» را بزند، ربات شما /start را همراه با payment_id می‌گیرد. با آن شناسه تأیید را بزنید:

curl -X POST "https://pay.pexn.ir/v2/payments/{payment_id}/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"

اگر پاسخ موفق بود و مقدار first_verification برابر true بود، سفارش را تحویل دهید. اگر false بود، یعنی پرداخت قبلاً تأیید و تحویل شده است و تحویل دوباره نباید انجام شود.

هیچ‌وقت فقط به دکمهٔ بازگشت یا اعلان بسنده نکنید

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

خطاهای متداول

• لینک ربات در callback_url. آنجا باید نشانی سرور باشد، نه لینک ربات.
• ربات یا دامنه ثبت نشده است. در پنل، صفحهٔ «درخواست درگاه پرداخت» را بررسی کنید.
• گرد کردن مبلغ. مشتری باید دقیقاً همان رقم نشان‌داده‌شده را واریز کند.
• تحویل بدون تأیید. همیشه ابتدا Verify.

مرجع و آزمایش

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

اگر ربات تلگرام هم دارید، آموزش تلگرام تقریباً همین مسیر است و اگر هنوز نمی‌دانید کدام روش دریافت پول برایتان مناسب است، این مقاله را بخوانید.

برچسب‌ها: #درگاه_پرداخت_ربات_بله #ربات_بله #آموزش_API #کارت_به_کارت_خودکار #پی‌اکسا