Paiements bot, de bout en bout

Stars — pas de setup, juste utiliser currency: "XTR". Les fonds atterrissent dans le wallet Stars de votre bot. Fiat — parler à @BotFather → Payments et connecter un provider (Stripe, Smart Glocal, YooKassa, Tranzzo, selon géographie). Vous obtiendrez un provider token à passer dans les invoices.

Pour 99% des produits digitaux, démarrez avec Stars et sautez la fiat dance entièrement.

Le chemin le plus simple est sendInvoice directement dans un chat :

await fetch(`https://api.telegram.org/bot${TOKEN}/sendInvoice`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    chat_id: userId,
    title: "Plan Pro, mensuel",
    description: "Accès illimité pendant 30 jours.",
    payload: `pro_${userId}_${Date.now()}`,
    currency: "XTR",
    prices: [{ label: "Pro", amount: 250 }],
  }),
});

payload est votre clé d’idempotence privée — ne l’exposez jamais à l’utilisateur, mettez-y toujours assez pour identifier la commande de votre côté.

Pour les Mini Apps, utilisez createInvoiceLink à la place, puis appelez WebApp.openInvoice(url) côté client.

Telegram vous envoie un update pre_checkout_query avant de débiter. Vous devez répondre dans 10 secondes, ou le paiement auto-fail.

// dans votre handler d'updates
if (update.pre_checkout_query) {
  const ok = await canFulfill(update.pre_checkout_query.invoice_payload);
  await fetch(`https://api.telegram.org/bot${TOKEN}/answerPreCheckoutQuery`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      pre_checkout_query_id: update.pre_checkout_query.id,
      ok,
      error_message: ok ? undefined : "Plus de stock — désolé.",
    }),
  });
}

Utilisez ce hook pour : re-valider le stock, vérifier la fraude, confirmer que l’utilisateur n’est pas banni, locker l’inventaire.

Après débit, vous recevez message.successful_payment sur le même chat. Le payload est votre clé d’idempotence — dédupez dessus.

if (update.message?.successful_payment) {
  const sp = update.message.successful_payment;
  await db.transaction(async (tx) => {
    const exists = await tx.payment.findUnique({ where: { payload: sp.invoice_payload } });
    if (exists) return;
    await tx.payment.create({ data: { ...sp, userId: update.message.chat.id } });
    await grantEntitlement(update.message.chat.id, sp.invoice_payload);
  });
  await sendMessage(update.message.chat.id, "Paiement reçu — vous êtes dedans. Tapez /start pour commencer.");
}

Telegram retry successful_payment jusqu’à ce que vous ack — votre handler doit être idempotent ou vous accordez l’accès deux fois.

Stars : refundStarPayment(user_id, telegram_payment_charge_id). Entièrement programmatique. Fiat : refund via le dashboard de votre provider (Stripe etc.) ; Telegram ne proxy pas les refunds fiat.

Construisez une commande admin /refund <order_id> dès le J1. Sans ça, vous ferez du SQL manuel dans une semaine.

Deux patterns :

Stars subscriptions (recommandé) — passez subscription_period: 2592000 (30 jours) sur l’invoice. Telegram facture l’utilisateur automatiquement chaque période. Vous recevez un successful_payment à chaque cycle.

Récurrent manuel — schedulez vos propres rappels de renouvellement, envoyez une fresh invoice à chaque cycle. Plus de boulot, mais vous contrôlez les retries, le dunning, les périodes de grâce.

Pour produits SaaS-like, les Stars subscriptions sont parfaites. Pour B2B haut-ticket, faites du récurrent manuel avec fiat.