چطور در ربات تلگرام پرداخت USDT بپذیریم

ربات‌های تلگرام یکی از بهترین جاها برای فروش کالای دیجیتال‌اند و یکی از بدترین جاها برای checkout سنتی. فرم کارت نیست، صفحه پرداخت میزبانی‌شده بومی نیست و کاربران از پرتاب به مرورگر متنفرند. درگاه با REST API ساده تناسب بهتری دارد: ربات invoice می‌سازد، جزئیات پرداخت را پیام می‌کند و وقتی webhook می‌گوید پول رسید واکنش نشان می‌دهد.

قبل از شروع چه لازم است

• توکن ربات از @BotFather.
• سروری که HTTPS بگیرد؛ بک‌اند ربات و گیرنده webhook می‌توانند یک اپ باشند.
• حساب VisualPay با 2FA، merchant ساخته‌شده و کلید API merchant از پنل. ثبت‌نام و اولین merchant رایگان است و KYC برای شروع لازم نیست.
• آدرس کیف تحت کنترل خودتان برای هر کوین و شبکه‌ای که می‌پذیرید، روی merchant اعلام‌شده.

شکل جریان

قبل از کد، دقیق باشید چه کسی چه می‌کند؛ اشتباه اینجا پول ربات را لو می‌دهد:

1. کاربر محصول را در ربات انتخاب می‌کند.
2. بک‌اند شما (نه کلاینت) درگاه را برای ساخت تراکنش صدا می‌زند.
3. ربات آدرس پرداخت، مبلغ دقیق USDT و مهلت را پیام می‌کند.
4. کاربر از کیف خودش می‌پردازد.
5. درگاه پرداخت را تشخیص می‌دهد و webhook شما را صدا می‌زند.
6. بک‌اند وضعیت را تأیید می‌کند، سفارش را paid می‌کند و ربات کالا را تحویل می‌دهد.

گام ۶ با گام ۵ شروع می‌شود، نه با کاری که کاربر در چت می‌کند. دکمه «پرداخت کردم» برای بررسی دوباره اشکالی ندارد؛ نباید محصول را آزاد کند.

گام ۱: شبکه را بپرسید

USDT روی چند زنجیره است و قابل جابه‌جایی نیست. اگر TRC20 را به آدرس ERC20 بفرستید، رفته. شبکه را صریح با inline keyboard انتخاب کنید:

{
  "inline_keyboard": [
    [{ "text": "USDT · TRC20 (Tron)",  "callback_data": "pay:USDT:trc20" }],
    [{ "text": "USDT · BEP20 (BSC)",   "callback_data": "pay:USDT:bep20" }],
    [{ "text": "USDT · ERC20 (Ethereum)", "callback_data": "pay:USDT:erc20" }]
  ]
}

TRC20 را اول بگذارید؛ کارمزد Tron برای خرید کوچک معمولاً دوستانه‌تر است.

گام ۲: تراکنش سمت سرور

با رسیدن callback query، بک‌اند invoice می‌سازد. کلید API در header است و هرگز از سرور خارج نمی‌شود:

const res = await fetch(
  'https://visualpay.net/api/v1/merchant/transaction/create',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.VISUALPAY_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      currency_symbol: 'USDT',
      network_code: 'trc20',
      amount_usd: 25.5,
      ttl: 20,
      order_id: order.id,
      comment: `Telegram user ${ctx.from.id}`,
    }),
  }
);

const tx = await res.json();

• ttl پنجره پرداخت به دقیقه و مدت قفل نرخ است؛ ۲۰ دقیقه برای ربات معقول است.
• order_id شناسه شماست؛ روی کاربر و چت ذخیره کنید تا webhook برگردد.
• comment متن آزاد در پنل است، برای پشتیبانی وقتی می‌گویند «پرداخت کردم چیزی نیامد».

tracking code برگشتی را فوراً به سفارش وصل و ذخیره کنید.

گام ۳: invoice به‌صورت پیام

درگاه داده برمی‌گرداند نه redirect؛ بومی نشان دهید. مبلغ و آدرس را monospace بگذارید تا با ضربه کپی شوند؛ آدرس را وسط خط نشکنید:

Send exactly:
1580.70 USDT

Network: TRC20 (Tron)

To address:
TXk...c72E

⏱ Expires in 20 minutes.

QR برای اسکن از دستگاه دوم مفید است. دکمه «بررسی پرداخت» که status endpoint را صدا بزند کافی است؛ کالا را آزاد نکند، فقط جایگزین پیام به پشتیبانی شود.

گام ۴: webhook

اینجا سفارش کامل می‌شود. endpoint باید HTTPS باشد و دفاعی نوشته شود:

app.post('/webhooks/visualpay', async (req, res) => {
  res.sendStatus(200);

  const { tracking_code } = req.body;

  const status = await verifyWithGateway(tracking_code);
  if (status !== 'confirmed') return;

  const order = await orders.findByTrackingCode(tracking_code);
  if (!order || order.fulfilled) return;

  await orders.markFulfilled(order.id);
  await bot.telegram.sendMessage(order.chat_id, 'Payment received. Here is your product: …');
});

سریع پاسخ دهید؛ handler کند باعث retry می‌شود. با status endpoint دوباره تأیید کنید، نه فقط body. idempotent بنویسید تا webhook دوبار محصول را دوبار نفرستد.

گام ۵: مسیرهای ناموفق

• Expired. پنجره بسته و پرداخت نشده. پیام را ویرایش کنید و «دوباره» را با تراکنش تازه بگذارید.
• Underpaid. داخل حاشیه تحمل merchant، پرداخت clear می‌شود و اعتبار از آنچه رسید محاسبه می‌شود؛ خارج حاشیه، واضح بگویید چه رسید و چه انتظار می‌رفت.
• Overpaid. پذیرفته می‌شود؛ سیاست مازاد را از قبل در ربات بگویید.
• Paid late. endpoint بررسی دوباره می‌تواند پرداخت on-chain برای تراکنش منقضی‌شده را بازیابی کند.

تسویه

VisualPay non-custodial است؛ پرداخت تأییدشده روی موجودی provider منتظر برداشت نمی‌ماند. با عبور از آستانه، خودکار به آدرس اعلام‌شده می‌رود، معمولاً زیر یک دقیقه، فقط با کارمزد زنجیره.

امنیت

• کلید API در env سرور؛ نه در کلاینت، مخزن کد یا پیام.
• webhook روی HTTPS و مسیر غیرقابل حدس.
• محدودیت نرخ روی دستور ساخت تراکنش.
• تطبیق شبانه تراکنش‌ها در برابر سفارش‌های خودتان.

چرا این الگو برای ربات مناسب است

افزونه نصب نمی‌کنید، SDK همگام نمی‌کنید و redirect مکالمه را نمی‌شکند. ربات همان رشته پیام است: invoice، پرداخت، تحویل. قفل نرخ، آدرس، رصد زنجیره و تسویه پشت دو فراخوانی HTTP و یک webhook می‌مانند.