Frais et limites de l’API marchand

Les factures entraînent 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 prélevés du côté marchand : le solde de votre application est crédité du montant net de frais.

Les frais de base représentent 3% du montant de la facture, avant application d’un éventuel palier de volume. Votre taux dépend des paliers configurés et du volume de factures payées sur les 30 derniers jours :

Deux règles comptent plus que le chiffre :

• Les frais sont calculés et fixé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 restituent 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 entraînent eux aussi des frais côté marchand ; chaque prélèvement indique son propre chiffre dans le champ charge.fee du webhook subscription_charged.

Les limites de transfert

transfer a un minimum et un maximum par transfert, exprimés en équivalent dollar américain plutôt qu’en montants propres à chaque actif. Traitez les erreurs amount_too_small et amount_too_big dans votre intégration lorsqu’un montant est refusé au titre de ces limites.

Un username inconnu crée un paiement en attente lorsque le mode de paiement sortant le permet ; voir les transferts et chèques.

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é.

La limite quotidienne de paiements sortants

Le propriétaire peut définir une limite sur 24 heures glissantes dans les paramètres des paiements de l’application. Les transferts, les chèques et les paiements depuis le solde de l’application partagent cette limite. Son dépassement renvoie 403 daily_cap_exceeded ; un lot est contrôlé avant son premier paiement. Les remboursements ne comptent pas dans cette limite. getMe renvoie daily_payout_max_usd_cents et daily_payout_spent_usd_cents.

Les restrictions du propriétaire peuvent aussi bloquer les transferts, les chèques et les remboursements (403 verification_required) ; une suspension temporaire renvoie 503 merchant_payouts_paused.

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 à 30 par minute, transfer à 30 par minute et transferBatch à 10 par minute. updateApp et createSubscriptionPlan ont aussi des limites ; voir la référence de l’API. En cas de rate_limited, augmentez le délai avant une nouvelle tentative.

L’idempotence

transfer exige un spend_id que vous générez ; createCheck et refundInvoice en acceptent un. Réutiliser la même valeur avec les mêmes paramètres renvoie le résultat d’origine au lieu de déplacer des fonds une seconde fois — ainsi vous pouvez réessayer une requête dont le délai de réponse a été dépassé 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. Des frais de plateforme peuvent s’appliquer aux factures et aux prélèvements d’abonnement. Une conversion automatique facultative utilise le devis d’échange. Alimenter le portefeuille d’un payeur depuis un portefeuille externe peut entraîner des frais facturés par ce portefeuille ou le réseau.

⚠️ 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 peut fausser votre comptabilité sans que vous le remarquiez. Lisez à chaque fois les frais enregistrés sur la facture.