آموزش اتصال درگاه پرداخت به ربات تلگرام؛ از ساخت پرداخت تا تحویل سفارش

اگر محصول، اشتراک یا شارژ را از راه ربات تلگرام می‌فروشید، مهم‌ترین سؤال این است که پرداخت را چطور داخل همان گفت‌وگو انجام دهید، بدون اینکه خودتان صفحهٔ پرداخت بسازید. در این آموزش، مسیر کامل اتصال ربات به بات آمادهٔ پی‌اکسا (@payexa_bot) را قدم‌به‌قدم توضیح می‌دهیم: از ساخت پرداخت تا تحویل سفارش.

ایده در یک پاراگراف

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

پیش‌نیازها

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

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

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

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": "TG-88-1024",
    "return_url": "https://t.me/YourBot",
    "callback_url": "https://your-bot-server.example.com/payexa/callback"
  }'

مبلغ به ریال است. لینک ربات باید در return_url باشد، نه callback_url؛ چون callback_url نشانی سرور است و لینک t.me در آن پذیرفته نمی‌شود.

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

{
  "ok": true,
  "data": {
    "payment_id": "A7F3C9E1B5D2468A0C1E3F5B7D9A2C4E6",
    "order_id": "TG-88-1024",
    "status": "pending",
    "telegram_url": "https://t.me/payexa_bot?start=pay_A7F3...",
    "payment_url": "/payment/start?authority=A7F3..."
  }
}

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

گام دوم: دکمهٔ پرداخت زیر پیام ربات

telegram_url را به‌صورت یک دکمهٔ لینک زیر پیام ربات خودتان بگذارید:

{
  "chat_id": 123456789,
  "text": "سفارش شما آماده است؛ برای پرداخت دکمهٔ زیر را بزنید.",
  "reply_markup": {
    "inline_keyboard": [[ { "text": "💳 پرداخت", "url": "<telegram_url>" } ]]
  }
}

مشتری چه چیزی می‌بیند؟

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

1. بات پی‌اکسا اول هشدار می‌دهد که مبلغ باید دقیقاً و بدون یک ریال کم یا زیاد واریز شود و مهلت پرداخت ۳۰ دقیقه است. مشتری باید «متوجه شدم» را بزند.
2. سپس شمارهٔ سفارش، مبلغ دقیق، شمارهٔ کارت مقصد و نام دارندهٔ کارت نشان داده می‌شود. دکمه‌هایی برای کپی شمارهٔ کارت، کپی مبلغ و بررسی وضعیت وجود دارد.
3. به‌محض تأیید پیامکی واریز، پیام تلگرام خودش به حالت موفق تغییر می‌کند. دکمهٔ «بازگشت به پذیرنده» پس از پرداخت (یا پایان مهلت) ظاهر می‌شود.

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

وقتی مشتری دکمهٔ بازگشت را بزند، ربات شما دستور /start را همراه با payment_id دریافت می‌کند. همین‌جا باید پرداخت را تأیید کنید:

def on_start(chat_id, text):
    parts = text.split(maxsplit=1)          # "/start A7F3..."
    if len(parts) != 2:
        return show_menu(chat_id)
    result = verify(parts[1])               # POST /v2/payments/{payment_id}/verify
    if result["ok"] and result["data"]["first_verification"]:
        deliver_order(result["data"]["order_id"])
        send_message(chat_id, "پرداخت شما تأیید شد؛ سفارش تحویل شد.")
    elif result["ok"]:
        send_message(chat_id, "این پرداخت قبلاً تأیید و تحویل شده است.")
    else:
        send_message(chat_id, result["error"]["message"])

درخواست تأیید این‌طور است:

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

قاعدهٔ اصلی: سفارش را فقط بعد از تأیید تحویل دهید

دکمهٔ بازگشت فقط برای راحتی مشتری است. اگر او آن را نزند، سفارش نباید گم شود. سه راه به همان تأیید ختم می‌شود:

• برگشت مشتری با /start؛
• اعلان امضاشده که به callback_url می‌آید؛
• برای رباتی که وب‌سرور ندارد، استعلام دوره‌ای وضعیت پرداخت تا وقتی وضعیت paid یا expired شود.

درخواست تأیید را می‌توان چند بار فرستاد. سفارش را فقط وقتی تحویل دهید که first_verification برابر true بود؛ به این ترتیب حتی اگر هر سه راه با هم فعال شوند، سفارش دو بار تحویل داده نمی‌شود.

اشتباه‌های رایج

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

آزمایش قبل از پرداخت واقعی

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

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

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