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 vor Anwendung einer Volumenstufe 3% des Rechnungsbetrags. Dein Satz hängt von den konfigurierten Stufen und dem Volumen bezahlter Rechnungen der zurückliegenden 30 Tage ab:

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.
• Dein Satz kann sich mit deinem Volumen ändern. Ein höheres Zahlungsvolumen über die zurückliegenden 30 Tage kann dich automatisch auf eine niedrigere Stufe bringen. Du beantragst das nicht und musst nichts einstellen.

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 bei Abo-Abbuchungen fällt eine Gebühr zulasten des Händlers an; jede Abbuchung meldet ihre eigene Zahl im Feld charge.fee des Webhooks subscription_charged.

Limits für Überweisungen

Für transfer gelten ein Minimum und ein Maximum pro Überweisung, angegeben als US-Dollar-Gegenwert statt als eigener Betrag pro Asset. Behandle in deiner Integration die Fehler amount_too_small und amount_too_big, falls ein Betrag aufgrund dieser Limits abgelehnt wird.

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 kein Nutzer der App ist – 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.

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: 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. Stufen und Sätze ändern sich, und eine veraltete Konstante verfälscht stillschweigend deine Buchhaltung. Lies die festgehaltene Gebühr jedes Mal von der Rechnung ab.