Référence de l’API : factures et remboursements

Les méthodes de facture : createInvoice, getInvoices, deleteInvoice, refundInvoice. Les conventions (authentification, enveloppe, montants, spend_id) sont sur la page Référence de l’API marchand ; le parcours guidé est Accepter des paiements avec des factures.

createInvoice

POST /pay/api/createInvoice — permission invoices, limite de 60 par minute.

Paramètre	Type	Requis	Signification
currency_type	string	non	crypto (défaut) ou fiat
asset	string	mode crypto	l’actif à facturer, par exemple USDT. Interdit en même temps que fiat
fiat	string	mode fiat	la monnaie fiduciaire dans laquelle le prix est libellé (les lignes is_fiat de getCurrencies)
accepted_assets	string / array	non	mode fiat uniquement : les actifs avec lesquels le payeur peut payer — une chaîne séparée par des virgules ("USDT,GRAM") ou un tableau JSON. Omis = tous les actifs pris en charge
amount	string	oui, sauf si open_amount est défini	chaîne décimale positive : unités de l’actif en mode crypto, unités fiduciaires (2 décimales au maximum) en mode fiat
open_amount	boolean	non	extension, mode crypto uniquement : pas de montant fixe — le payeur en saisit un au moment de payer (dons et pourboires). Exclusif avec amount
description	string	non	jusqu’à 1024 caractères, affichée au payeur
hidden_message	string	non	jusqu’à 2048 caractères, révélé au payeur seulement après le paiement
payload	string	non	jusqu’à 4096 caractères de vos propres données, renvoyés dans la facture et le webhook
allow_comments	boolean	non	laisse le payeur joindre un commentaire (défaut true)
allow_anonymous	boolean	non	laisse le payeur masquer son identité (défaut true)
paid_btn_name	string	non	bouton après paiement : viewItem, openChannel, openBot ou callback
paid_btn_url	string	non	l’URL http(s) du bouton — requise quand paid_btn_name est défini
swap_to	string	non	convertit automatiquement les paiements reçus dans cet actif. Au mieux : si la conversion ne peut pas s’exécuter au moment du paiement, le paiement réussit quand même sans conversion
expires_in	integer	non	secondes avant expiration de la facture, jusqu’à 2678400 (31 jours) ; omis ou 0 = jamais
rate_lock_seconds	integer	non	extension, mode fiat uniquement : fige les taux de conversion à la création pour cette fenêtre (voir plus bas)

Le résultat — et la charge utile du webhook invoice_paid — est l’objet facture. Ses champs clés :

• Identité et état : invoice_id, hash (l’identifiant public dans pay_url), status (active / paid / expired), pay_url — le lien t.me que vous envoyez au payeur (bot_invoice_url, mini_app_invoice_url, web_app_invoice_url en sont des alias).
• Montants : amount (la valeur nominale — unités fiduciaires sur une facture fiat, crypto sinon ; null tant qu’une facture à montant ouvert est impayée), amount_minor, et sur les factures fiat payées paid_asset / paid_amount / paid_fiat_rate — la crypto réellement facturée et le taux utilisé.
• Frais : fee_asset / fee_amount, apposés au paiement — le chiffre qui fait foi pour votre comptabilité (fee et usd_rate sont des alias Crypto Bot obsolètes). Voir frais et limites.
• Payeur : paid_by_user_id (null quand le payeur a choisi l’anonymat), paid_anonymously, comment.
• Remboursements (extension) : refunded_amount / refunded_minor (cumulés) et refunded_at, apposé une fois le remboursement complet.
• Taux bloqué (extension) : rate_lock_until et rate_lock_rates — les taux apposés par actif, null si aucun blocage n’a été demandé.
• Tels que créés : description, hidden_message, payload, paid_btn_name / paid_btn_url, expiration_date (expires_at en est un alias), les champs de conversion (swap_to, is_swapped, swapped_to, swapped_rate, swapped_output, …).

Erreurs : 400 invalid_currency (actif et fiat mélangés), 400 invalid_amount, 404 unknown_asset, 400 unsupported_fiat, 400 paid_btn_url_required, et pour les demandes de blocage de taux 400 rate_lock_fiat_only, 409 ratelock_disabled, 409 rate_unavailable (pas de taux frais pour un actif accepté — réessayez).

Comment les factures sont payées

Le payeur paie depuis le solde de son portefeuille dans la Mini App — instantanément, sans frais de réseau. Un payeur peut aussi alimenter la facture depuis un portefeuille externe : l’app lui affiche une adresse de dépôt, son transfert arrive sur son propre portefeuille, et la facture se règle automatiquement dès son arrivée. Dans les deux cas vous voyez la même chose : une facture paid normale et un webhook invoice_paid — il n’y a ni paramètre ni champ supplémentaire à gérer.

Sur une facture fiat, le montant en crypto est calculé au moment du paiement, arrondi à la hausse en votre faveur, de sorte que vous ne recevez jamais moins que la valeur nominale en monnaie fiduciaire. Si aucun taux frais n’est disponible, le paiement échoue du côté du payeur plutôt que de se régler à un taux obsolète.

Bloquer le taux sur une facture fiat

Passez rate_lock_seconds pour apposer le taux courant de chaque actif accepté à la création. Tant que le blocage est actif, le payeur voit exactement les montants apposés, et le paiement se convertit au taux apposé — vous prenez le risque de change pendant la fenêtre. Le serveur borne la fenêtre entre 60 secondes et le maximum de la plateforme (actuellement 15 minutes).

Quand le blocage expire, la facture reste payable et revient discrètement à la conversion au moment du paiement. Si vous voulez que la facture meure avec le devis, réglez expires_in sur la même valeur.

getInvoices

GET /pay/api/getInvoices — permission read. Filtres : asset, fiat, invoice_ids (séparés par des virgules), status (active / paid / expired — expired est une extension ; active exclut les factures déjà passées leur échéance), plus offset / count. Renvoie {"items": [invoice, …]}, les plus récentes d’abord.

deleteInvoice

POST /pay/api/deleteInvoice — permission invoices. Un seul paramètre : invoice_id. Annule une facture impayée et renvoie true. Erreurs : 404 invoice_not_found, 409 invoice_already_paid — une facture payée ne peut pas être supprimée, l’argent a déjà bougé.

refundInvoice

POST /pay/api/refundInvoice — permission refunds, limite de 30 par minute. Une extension par rapport à Crypto Bot : renvoie le montant nominal d’une facture payée — ou une partie — depuis le solde de votre application vers celui qui l’a payée, payeurs anonymes compris, sans révéler qui ils étaient.

Paramètre	Type	Requis	Signification
invoice_id	integer	oui	la facture payée
amount	string	non	le montant à rembourser, dans l’actif de la facture. Omis = tout le reliquat non remboursé. Les remboursements partiels s’additionnent jusqu’au montant nominal
spend_id	string	non	clé d’idempotence — utilisez-en une, pour qu’un réessai après expiration rejoue au lieu de rembourser deux fois

Le résultat est l’objet facture mis à jour avec les cumuls refunded_amount / refunded_minor ; refunded_at est apposé une fois la facture entièrement remboursée. Le statut reste paid. Les frais de plateforme ne sont pas rendus. Chaque remboursement déclenche le webhook facultatif refund_completed.

Erreurs : 404 invoice_not_found, 409 invoice_not_paid, 409 already_refunded (plus rien à rembourser), 409 amount_too_big (plus que le reliquat non remboursé), 409 insufficient_funds, 400 invalid_amount, et la paire spend_id 409 idempotency_conflict / 409 idempotency_in_progress.