Accepter des paiements avec des factures

Une facture est la façon dont vous facturez un utilisateur Telegram. Vous en créez une via l’API, envoyez son lien au payeur, et le solde de votre application est crédité à l’instant où il confirme.

Le déroulé

1. Créez la facture avec createInvoice, en donnant un actif et un montant (ou un prix en monnaie fiduciaire — voir plus bas).
2. Envoyez le lien au payeur depuis la réponse. L’ouvrir l’amène sur l’écran Payer dans l’app.
3. Il confirme et paie depuis son solde — instantanément, sans frais de réseau. Un payeur dont le solde ne suffit pas peut alimenter la facture depuis un portefeuille externe ; elle se règle automatiquement quand son transfert arrive, et pour vous cela ne change rien.
4. Vous êtes prévenu. Le webhook invoice_paid se déclenche, et le montant arrive sur le solde de votre application.
5. Honorez la commande. N’attendez rien d’autre ; le paiement est définitif à ce stade.

Si vous préférez interroger l’API plutôt que recevoir un webhook, getInvoices renvoie vos factures avec leur statut actuel. Le webhook est la voie la plus rapide — l’interrogation est la solution de repli.

Facturer en monnaie fiduciaire

Une facture peut être libellée en crypto, ou dans une monnaie fiduciaire avec une liste d’actifs acceptés. Le payeur règle alors dans celui des actifs acceptés qu’il détient, converti au cours du moment du paiement. C’est le choix habituel pour une boutique dont le catalogue est libellé dans une monnaie du monde réel.

Si vous préférez annoncer un prix ferme, rate_lock_seconds fige les taux de conversion à la création pour une fenêtre limitée — le payeur voit exactement les montants bloqués, et vous prenez le risque de change pendant ces minutes. Détails dans la référence des factures.

Vous pouvez aussi définir swap_to pour que les paiements entrants soient convertis en un actif unique à leur arrivée — pratique pour garder votre solde en stablecoin sans piloter les échanges vous-même.

Options de facture utiles

• description — affichée au payeur sur l’écran Payer.
• hidden_message — révélé au payeur seulement après son paiement. C’est ainsi que vous livrez un code, une clé ou un lien sans canal de livraison séparé.
• payload — votre propre chaîne opaque, renvoyée telle quelle dans le webhook. Mettez-y votre identifiant de commande.
• expires_in — une limite de temps, au-delà de laquelle la facture ne peut plus être payée.
• paid_btn_name / paid_btn_url — le bouton que voit le payeur après avoir payé, pour le renvoyer vers votre bot, votre chaîne ou la page de l’article.
• open_amount — pas de montant fixe ; le payeur en saisit un au moment de payer. La forme naturelle pour les dons et les pourboires.

Une facture impayée peut être annulée avec deleteInvoice.

Les remboursements

refundInvoice renvoie le montant nominal d’une facture payée — ou une partie quelconque — depuis le solde de votre application vers celui qui l’a payée, payeurs anonymes compris, sans révéler qui ils étaient. Les remboursements partiels s’additionnent jusqu’au montant nominal ; la facture les suit dans refunded_amount. Passez un spend_id pour qu’un réessai après expiration rejoue au lieu de rembourser deux fois. Les frais de la plateforme ne sont pas remboursés.

⚠️ Vérifiez la signature du webhook avant d’honorer

N’importe qui peut envoyer un POST à votre URL de webhook. Vérifiez l’en-tête TgCryptoPay-API-Signature — un HMAC-SHA256 sur le corps brut de la requête, avec pour clé le SHA-256 de votre token d’API — avant de considérer un paiement comme réel, et dédupliquez sur update_id pour qu’un réessai n’expédie pas la commande deux fois.