پرش به محتوای اصلی

ربات تلگرام فروشنده: کد و اشتراک را بعد از پرداخت واقعی تحویل دهید

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

جریان یک سفارش

از «خرید» تا تحویل، در چهار گام

  1. مشتری «خرید» را می‌زند

    ربات شما با یک درخواست POST /v1/links برای این سفارش یک لینک تک‌بارمصرف می‌سازد و شناسه چت و محصول را در metadata می‌گذارد.

  2. ربات لینک را می‌فرستد

    لینک را با دکمه «پرداخت» برای همان مشتری می‌فرستید. مشتری کارت‌به‌کارت می‌کند و پول مستقیم به کارت شما می‌رود.

  3. خبر پرداخت به ربات می‌رسد

    یا وب‌هوک امضاشده می‌آید، یا ربات هر چند ثانیه GET /v1/events را می‌پرسد. این فقط خبر است، نه مدرک.

  4. verify، سپس تحویل یک‌بار

    ربات پرداخت را از API می‌خواند و فقط اگر verified برابر true بود، کد را به شناسه پرداخت اختصاص می‌دهد، ذخیره می‌کند و می‌فرستد.

نمونه کد کوتاه

دو تکه کد کافی است: ساخت لینک برای هر سفارش، و یک تابع واحد برای تحویل که هم وب‌هوک و هم poll فقط شناسه پرداخت را به آن می‌دهند. این بریده‌ای کوتاه از الگوی کار است؛ نمونه کامل‌تر و دو ربات آماده (Node با grammY و Python با aiogram) در مخزن پروژه است.

// one single-use link per order; the chat and product ride along in metadata
const res = await fetch(`${API}/v1/links`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: priceToman * 10,                 // rial, an integer
    title: product.title,
    metadata: { chat_id: ctx.chat.id, sku: product.sku },
    external_ref: `tg-${ctx.callbackQuery.id}`, // a retried update returns the same link
  }),
});
const { url } = await res.json();            // send it with a "Pay" button
// the ONE function that delivers; the webhook and the poller both call it with a payment id
async function deliverIfPaid(paymentId: string) {
  if (db.isDelivered(paymentId)) return;       // UNIQUE(payment_id) in your database
  const p = await getPayment(paymentId);       // GET /v1/payments/{id}, never the event's own status
  if (!p.verified || !['paid', 'paid_late'].includes(p.status)) return;
  if (p.amount_rial !== priceRial(p.metadata.sku)) return; // is it really for this product?
  const code = db.assignCode(paymentId);       // save first ...
  await bot.api.sendMessage(p.metadata.chat_id, code); // ... then send
  db.markDelivered(paymentId);
}

مبلغ‌ها به ریال و عدد صحیح‌اند. کلید sk_live_… و رمز وب‌هوک را فقط در متغیر محیطی نگه دارید، نه در کد، لاگ یا پیام تلگرام.

خبر پرداخت: وب‌هوک یا poll

هر دو را می‌توانید با هم داشته باشید؛ تحویل یکتا کاری می‌کند که جواب یکی بشود.

وب‌هوکpoll کردن رویدادها
نیازآدرس عمومی https برای رباتهیچ آدرس عمومی؛ ربات از کامپیوتر خانه هم کار می‌کند
چطورPOST امضاشده با هدر X-SignatureGET /v1/events?after=cursor، هر ۲ تا ۵ ثانیه
قاعدهبدنه خام را با HMAC-SHA256 بررسی کنید؛ بعد از انجام کار 2xx بدهیدرویداد را پردازش کنید، بعد cursor را ذخیره کنید
تضمینحداقل یک‌بار؛ شناسه رویداد تکراری را نادیده بگیریدحداقل یک‌بار؛ رویدادها هفت روز نگه داشته می‌شوند

تحویل ایمن کد یا حساب

  1. خبر پرداخت اثبات نیست. وب‌هوک و رویداد فقط می‌گویند «به این پرداخت نگاه کن». پرداخت را از API بخوانید و فقط اگر verified برابر true و وضعیت paid یا paid_late بود تحویل دهید.
  2. مطمئن شوید پرداخت مال شماست. metadata را بخوانید و مبلغ را با قیمت محصول مقایسه کنید.
  3. اول ذخیره، بعد ارسال. کد را به شناسه پرداخت اختصاص دهید و ذخیره کنید، بعد بفرستید، بعد «تحویل شد» را ثبت کنید. اگر ارسال شکست خورد، تلاش بعدی همان کد را می‌فرستد، نه کد دیگری.
  4. تحویل را یکتا کنید. برای «کد» هر چیزی که می‌فروشید (آدرس دانلود، نام کاربری و رمز، …) همین قاعده است.
رسید تصویری و بازگشت مرورگر مدرک نیستند

مشتری می‌تواند رسید جعلی بفرستد. فقط verified بودن پرداخت در API معتبر است.

آزمایش بدون پول واقعی

با کلید sk_test_… لینک آزمایشی بسازید و پرداختش را شبیه‌سازی کنید؛ همان موتور تطبیق، همان اعلان و همان صفحه پرداخت، بدون کارمزد:

curl -X POST $API/v1/test/deposits \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "payment_id": "pay_..." }'

چیزهایی که باید بدانید

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

پرسش‌های ربات‌نویس‌ها

ربات من آدرس عمومی ندارد. باز هم می‌شود؟

بله. به‌جای وب‌هوک، ربات خودش GET /v1/events را هر ۲ تا ۵ ثانیه می‌پرسد و با cursor دقیقاً از جایی که مانده ادامه می‌دهد. رویدادها هفت روز نگه داشته می‌شوند. این کار روی کامپیوتر خانه هم جواب می‌دهد.

اگر وب‌هوک دو بار برسد یا ربات وسط کار بمیرد، کد دو بار تحویل داده می‌شود؟

نباید. تحویل را با شناسه پرداخت یکتا می‌کنید: کد را به شناسه پرداخت اختصاص می‌دهید و ذخیره می‌کنید، بعد می‌فرستید. در محصول واقعی این یک قید UNIQUE(payment_id) در پایگاه داده است تا خود پایگاه داده تحویل دوم را ناممکن کند.

مشتری کمتر یا بیشتر واریز کرد چه می‌شود؟

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

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

نه. پیش‌نمایش تلگرام و واتس‌اپ فقط عنوان و مبلغ را می‌بیند و پرداختی نمی‌سازد؛ فقط باز کردن واقعی لینک پرداخت می‌سازد.

ربات را بدون پول واقعی امتحان کنم؟

بله. با کلید sk_test_ لینک آزمایشی می‌سازید و با یک درخواست POST /v1/test/deposits پرداخت را «انجام» می‌دهید. همان موتور تطبیق، همان اعلان و همان صفحه پرداخت است و کارمزد ندارد.

ربات‌تان را به پرداخت وصل کنید

با کلید آزمایشی شروع کنید و وقتی مطمئن شدید، کلید واقعی بگیرید.