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

Auf Rechnungen fällt eine Plattformgebühr an, die von dem abgeht, was du erhältst; Ü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 3% des Rechnungsbetrags und sinkt automatisch mit deinem Zahlungsvolumen der zurückliegenden 30 Tage:

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

transfer ist durch ein Minimum und ein Maximum pro Überweisung begrenzt, angewendet als geschätzter US-Dollar-Gegenwert zu aktuellen Kursen statt als Zahl pro Asset. Ein Betrag außerhalb dieses Bereichs wird mit einem ausdrücklichen Fehler abgelehnt – behandle amount_too_small und amount_too_big also in deiner Integration.

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 Ausschüttung 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.

Anfragelimits

Die Methoden, die Geld bewegen, sind pro App begrenzt (geteilt über alle ihre Token): createInvoice und createCheck auf 60 pro Minute, refundInvoice und transfer auf 30, transferBatch auf 10. Lesende Methoden sind unbegrenzt. Eine gut gebaute Integration merkt davon nichts; eine Schleife aus Wiederholungen schon – warte bei rate_limited ab, statt weiter zu hämmern.

Idempotenz

transfer verlangt eine spend_id, die du selbst erzeugst; createCheck und refundInvoice akzeptieren eine. Denselben Wert 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 Ausschüttung 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ühr auf Rechnungen ist die einzige Gebühr.

⚠️ 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.