Accepter des paiements avec des factures

Une facture permet de demander un paiement à un utilisateur Telegram. Vous la créez via l’API, puis envoyez son lien au payeur. Une fois le paiement effectué, le solde de votre application est crédité du montant, déduction faite des frais marchands.

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 la facture 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 lorsque cette option est disponible. Le paiement automatique nécessite un solde crédité suffisant avant l’échéance et l’absence de restriction sur les paiements sortants. Un dépôt ne prouve pas à lui seul que la facture a été payée.
4. Vous êtes prévenu. Si vous avez configuré une URL de webhook, un événement invoice_paid est mis en attente d’envoi après le paiement. Votre application reçoit le montant moins les frais.
5. Honorez la commande. Vérifiez d’abord la signature du webhook, associez la facture à votre commande et confirmez que son statut est paid. Vous pouvez aussi vérifier ce statut avec getInvoices. Aucune confirmation supplémentaire de la blockchain n’est nécessaire.

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é en monnaie fiduciaire.

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 seul actif lorsque la conversion est disponible. Si elle ne peut pas avoir lieu, le paiement aboutit tout de même dans l’actif d’origine ; vérifiez is_swapped et les champs swapped_*.

Options de facture utiles

• description — affichée au payeur sur l’écran Payer la facture.
• 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. Une option adaptée aux dons et aux pourboires.

La description, le contenu après paiement et le bouton peuvent rester masqués aux payeurs tant que le contenu n’a pas été approuvé. Ne comptez pas sur leur disponibilité immédiate après la création de la facture.

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

Les remboursements

refundInvoice rembourse le montant en crypto effectivement payé — ou une partie de ce montant — depuis le solde de votre application au payeur, y compris s’il a payé anonymement, sans révéler son identité. Les remboursements partiels se cumulent jusqu’au montant en crypto initialement payé ; la facture enregistre leur total dans refunded_amount. Pour une facture en monnaie fiduciaire, utilisez paid_asset et paid_amount, pas la valeur nominale en monnaie fiduciaire. Votre application doit disposer d’un solde suffisant dans l’actif payé à l’origine, même après une conversion automatique. Passez un spend_id afin qu’une nouvelle tentative après un délai de réponse dépassé renvoie le résultat précédent sans rembourser deux fois. Les frais de la plateforme ne sont pas remboursés.

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

N’importe qui peut envoyer un POST à votre URL de webhook. Vérifiez l’en-tête TgPayCrypto-API-Signature — un HMAC-SHA256 sur le corps brut de la requête, avec pour clé le SHA-256 de votre token d’API principal — avant de considérer un paiement comme réel, et dédupliquez sur update_id pour qu’une nouvelle tentative n’entraîne pas un double envoi de la commande.