Frais et limites de l’API marchand

Les factures portent des frais de plateforme prélevés sur ce que vous recevez ; les transferts et les chèques sont encadrés par des limites de montant. Les chiffres ci-dessous sont les paramètres actuels, pas des conditions contractuelles — quand ils divergent de ce que vous voyez, c’est l’app qui a raison, et la source fiable reste toujours vos propres factures payées.

Les frais sur facture

Le payeur paie toujours le montant nominal de la facture. Les frais sont pris du côté commerçant : le solde de votre application est crédité du montant net de frais.

Les frais sont de 3% du montant de la facture, et ils baissent automatiquement avec votre volume de paiements des 30 derniers jours :

Volume sur 30 jours	Frais
moins de 10 000 $	3%
à partir de 10 000 $	2,9%
à partir de 25 000 $	2,8%
à partir de 50 000 $	2,7%
à partir de 75 000 $	2,6%
à partir de 100 000 $	2,5%

Deux règles comptent plus que le chiffre :

Les frais sont résolus et figés au moment du paiement. Un changement ultérieur du taux ne touche jamais une facture déjà payée.
Votre taux peut changer avec votre volume. Un volume de paiements plus élevé sur une fenêtre glissante de 30 jours peut vous faire passer automatiquement à un palier inférieur. Il n’y a pas de demande à faire ni rien à configurer.

Pour voir exactement ce qui a été prélevé, lisez fee_asset et fee_amount sur la facture payée — depuis la charge utile du webhook invoice_paid ou depuis getInvoices. C’est le chiffre qui fait foi pour votre comptabilité.

Les remboursements ne rendent pas les frais : ce que refundInvoice envoie au payeur sort de votre solde, et les frais ne sont pas remboursés — y compris sur un remboursement partiel.

Les prélèvements d’abonnement portent eux aussi des frais côté commerçant ; chaque prélèvement indique son propre chiffre dans le champ charge.fee du webhook subscription_charged.

Les limites de transfert

transfer est encadré par un minimum et un maximum par transfert, appliqués comme une estimation en équivalent dollar américain aux cours du moment plutôt qu’en chiffre par actif. Un montant hors de cette plage est rejeté avec une erreur explicite : traitez donc amount_too_small et amount_too_big dans votre intégration.

Un transfert échoue aussi quand :

le solde de votre application est insuffisant dans cet actif,
le destinataire n’est pas un utilisateur de l’app — un paiement vers un identifiant Telegram inconnu ou mal saisi renvoie une erreur au lieu de créditer un portefeuille que personne n’ouvrira,
le compte du destinataire est bloqué.

Les limites de débit

Les méthodes qui déplacent de l’argent sont limitées en débit par application (tous ses tokens confondus) : createInvoice et createCheck à 60 par minute, refundInvoice et transfer à 30, transferBatch à 10. Les méthodes de lecture sont illimitées. Une intégration bien élevée ne s’en aperçoit jamais ; une boucle de réessais, si — temporisez sur rate_limited plutôt que de marteler.

L’idempotence

transfer exige un spend_id que vous générez ; createCheck et refundInvoice en acceptent un. Réutiliser la même valeur rejoue le résultat d’origine au lieu de déplacer des fonds une seconde fois — ainsi une requête expirée peut être réessayée sans risque avec le même spend_id, et seul un paiement réellement nouveau en reçoit un nouveau.

Ce qui ne coûte rien

Il n’y a aucun frais de réseau nulle part dans l’API marchand — factures, transferts et chèques se règlent tous à l’intérieur de l’app, hors chaîne. Les frais de plateforme sur les factures sont le seul prélèvement.

⚠️ Ne calculez jamais les frais vous-même

Ne codez pas un pourcentage en dur et ne reconstituez pas le net à partir du montant nominal. Les paliers et les taux changent, et une constante obsolète corrompt votre comptabilité en silence. Lisez à chaque fois les frais enregistrés sur la facture.