Gebühren und Limits bei der Händler-API

Auf Rechnungen fällt eine Plattformgebühr an, die von deinem Zahlungseingang abgezogen wird; Überweisungen und Schecks sind durch Betragslimits begrenzt. Die Zahlen unten sind die aktuellen Einstellungen, keine Vertragsbedingungen – wenn sie von dem abweichen, was du siehst, gilt die App, und die verlässliche Quelle sind immer deine eigenen bezahlten Rechnungen.

Die Gebühr auf Rechnungen

Der Zahler zahlt immer den Nennbetrag der Rechnung. Die Gebühr geht zulasten des Händlers: Deinem App-Guthaben wird der Betrag abzüglich der Gebühr gutgeschrieben.

Die Gebühr beträgt 1,5% des Rechnungsbetrags. Der Satz ist für jede Rechnung gleich, Volumenrabatte gibt es nicht.

Zwei Regeln sind wichtiger als die Zahl selbst:

• Die Gebühr wird im Moment der Zahlung ermittelt und festgeschrieben. Eine spätere Änderung des Satzes berührt eine bereits bezahlte Rechnung nie.
• Die Gebühr wird abgerundet auf die kleinste Einheit des Assets, sodass eine sehr kleine Rechnung ganz ohne Gebühr bleiben kann.

Um genau zu sehen, was berechnet wurde, lies fee_asset und fee_amount von der bezahlten Rechnung ab – aus dem Payload des Webhooks invoice_paid oder aus getInvoices. Das ist die maßgebliche Zahl für deine Bücher.

Rückerstattungen geben die Gebühr nicht zurück: Was refundInvoice an den Zahler schickt, geht von deinem Guthaben ab, und die Gebühr wird nicht erstattet – auch nicht bei einer Teilerstattung.

Auch für Abo-Abbuchungen kann eine Händlergebühr anfallen – aktuell 0%. Die Gebühr jeder Abbuchung steht im Feld charge.fee des Webhooks subscription_charged.

Limits für Überweisungen

Für transfer gilt ein Maximum pro Überweisung von 25.000 $, als US-Dollar-Gegenwert statt als eigener Betrag je Asset. Ein Minimum pro Überweisung kann ebenfalls festgelegt werden; derzeit gibt es keines. Behandle in deiner Anbindung amount_too_big und, falls ein Minimum eingeführt wird, amount_too_small, wenn diese Grenzen zur Ablehnung eines Betrags führen (beide sind 400). Für ein Asset, das gerade keinen US-Dollar-Kurs hat, gilt das Maximum nicht.

Ein unbekannter username erstellt dagegen eine ausstehende Auszahlung, wenn der Auszahlungsmodus das zulässt; siehe Überweisungen und Schecks.

Eine Überweisung schlägt außerdem fehl, wenn:

• dein App-Guthaben in diesem Asset nicht reicht,
• der Empfänger TgPay Crypto noch nie geöffnet hat – eine Auszahlung an eine unbekannte oder vertippte Telegram-ID führt zu einem Fehler, statt den Betrag einer Wallet gutzuschreiben, die niemand öffnen wird,
• das Konto des Empfängers gesperrt ist – gemeldet mit demselben 404 user_not_found.

Tägliches Auszahlungslimit

Der Inhaber kann in den Auszahlungseinstellungen der App ein Limit für die jeweils zurückliegenden 24 Stunden festlegen. Überweisungen, Schecks und Auszahlungen aus dem App-Guthaben teilen sich dieses Limit. Bei Überschreitung wird 403 daily_cap_exceeded zurückgegeben; ein Stapel wird vor der ersten Auszahlung geprüft. Erstattungen zählen nicht dazu. getMe liefert daily_payout_max_usd_cents und daily_payout_spent_usd_cents.

Einschränkungen des Inhaberkontos können auch Überweisungen, Schecks und Erstattungen blockieren (403 verification_required). Eine vorübergehende Pause führt zu 503 merchant_payouts_paused.

Anfragelimits

Die Methoden, die Geld bewegen, sind pro App begrenzt; alle ihre Token teilen sich die Limits, jede Methode wird getrennt gezählt: createInvoice und createCheck auf 60 pro Minute, refundInvoice auf 30 pro Minute, transfer auf 30 pro Minute und transferBatch auf 10 pro Minute. Auch updateApp und createSubscriptionPlan haben Limits; siehe die API-Referenz. Verlängere bei rate_limited die Wartezeit vor dem nächsten Versuch.

Idempotenz

transfer verlangt eine spend_id, die du selbst erzeugst; createCheck und refundInvoice akzeptieren eine. Denselben Wert mit denselben Parametern erneut zu verwenden gibt das ursprüngliche Ergebnis wieder, statt ein zweites Mal Guthaben zu bewegen – eine Anfrage nach einem Timeout kannst du also gefahrlos mit derselben spend_id wiederholen, und nur eine wirklich neue Auszahlung bekommt eine neue.

Was nichts kostet

Bei der Händler-API fällt nirgends eine Netzwerkgebühr an – Rechnungen, Überweisungen und Schecks werden alle innerhalb der App abgewickelt, off-chain. Die Plattformgebühren können auf Rechnungen und Abo-Abbuchungen anfallen. Ein optionaler automatischer Tausch verwendet das Tauschangebot. Zahlt ein Nutzer aus einer externen Wallet ein, können Gebühren dieser Wallet oder des Netzwerks anfallen.

⚠️ Leite die Gebühr nie selbst her

Schreibe keinen Prozentsatz fest ins Programm und rekonstruiere den Nettobetrag nicht aus dem Nennbetrag. Der Satz kann sich ändern, und eine veraltete Konstante verfälscht stillschweigend deine Buchhaltung. Lies die festgehaltene Gebühr jedes Mal von der Rechnung ab.