API-Referenz: Rechnungen und Rückerstattungen

Die Methoden rund um Rechnungen: createInvoice, getInvoices, deleteInvoice, refundInvoice. Die Konventionen (Authentifizierung, Hülle, Beträge, spend_id) stehen auf der Seite Händler-API-Referenz; die geführte Anleitung ist Zahlungen mit Rechnungen annehmen.

createInvoice

POST /pay/api/createInvoice – Berechtigung invoices, Limit 60 pro Minute.

Parameter	Typ	Pflicht	Bedeutung
currency_type	string	nein	crypto (Standard) oder fiat
asset	string	Krypto-Modus	das Asset, das berechnet wird, z. B. USDT. Nicht zusammen mit fiat erlaubt
fiat	string	Fiat-Modus	die Fiat-Währung, in der der Preis angegeben ist (die is_fiat-Zeilen von getCurrencies)
accepted_assets	string / array	nein	nur im Fiat-Modus: die Assets, mit denen der Zahler zahlen darf – ein kommagetrennter String ("USDT,GRAM") oder ein JSON-Array. Weggelassen = alle unterstützten Assets
amount	string	ja, außer wenn open_amount gesetzt ist	positiver Dezimalstring: Asset-Einheiten im Krypto-Modus, Fiat-Einheiten (max. 2 Nachkommastellen) im Fiat-Modus
open_amount	boolean	nein	Erweiterung, nur im Krypto-Modus: kein fester Betrag – der Zahler gibt ihn bei der Zahlung ein (Spenden und Trinkgelder). Schließt sich mit amount gegenseitig aus
description	string	nein	bis zu 1024 Zeichen, wird dem Zahler angezeigt
hidden_message	string	nein	bis zu 2048 Zeichen, wird dem Zahler erst nach der Zahlung gezeigt
payload	string	nein	bis zu 4096 Zeichen eigener Daten, die auf der Rechnung und im Webhook zurückgegeben werden
allow_comments	boolean	nein	erlaubt dem Zahler, einen Kommentar anzuhängen (Standard true)
allow_anonymous	boolean	nein	erlaubt dem Zahler, seine Identität zu verbergen (Standard true)
paid_btn_name	string	nein	Button nach der Zahlung: viewItem, openChannel, openBot oder callback
paid_btn_url	string	nein	die http(s)-URL des Buttons – Pflicht, wenn paid_btn_name gesetzt ist
swap_to	string	nein	tauscht empfangene Zahlungen automatisch in dieses Asset. Nach bestem Bemühen: Lässt sich der Tausch bei der Zahlung nicht ausführen, gelingt die Zahlung trotzdem ohne Tausch
expires_in	integer	nein	Sekunden, bis die Rechnung abläuft, bis zu 2678400 (31 Tage); weggelassen oder 0 = nie
rate_lock_seconds	integer	nein	Erweiterung, nur im Fiat-Modus: schreibt die Umrechnungskurse bei der Erstellung für dieses Zeitfenster fest (siehe unten)

Das Ergebnis – und der Payload des Webhooks invoice_paid – ist das Rechnungsobjekt. Seine wichtigsten Felder:

• Identität und Zustand: invoice_id, hash (die öffentliche ID in pay_url), status (active / paid / expired), pay_url – der t.me-Link, den du dem Zahler schickst (bot_invoice_url, mini_app_invoice_url, web_app_invoice_url sind Aliasse davon).
• Beträge: amount (der Nennwert – Fiat-Einheiten auf einer Fiat-Rechnung, sonst Krypto; null, solange eine Rechnung mit freiem Betrag unbezahlt ist), amount_minor und auf bezahlten Fiat-Rechnungen paid_asset / paid_amount / paid_fiat_rate – die tatsächlich berechnete Krypto und der verwendete Kurs.
• Gebühr: fee_asset / fee_amount, bei der Zahlung festgehalten – die maßgebliche Zahl für deine Bücher (fee und usd_rate sind veraltete Crypto-Bot-Aliasse). Siehe Gebühren und Limits.
• Zahler: paid_by_user_id (null, wenn der Zahler Anonymität gewählt hat), paid_anonymously, comment.
• Rückerstattungen (Erweiterung): refunded_amount / refunded_minor (kumuliert) und refunded_at, festgehalten, sobald die Rechnung vollständig erstattet wurde.
• Kursfestschreibung (Erweiterung): rate_lock_until und rate_lock_rates – die festgehaltenen Kurse pro Asset, null, wenn keine Festschreibung angefordert wurde.
• Wie erstellt: description, hidden_message, payload, paid_btn_name / paid_btn_url, expiration_date (expires_at ist ein Alias), die Tausch-Felder (swap_to, is_swapped, swapped_to, swapped_rate, swapped_output, …).

Fehler: 400 invalid_currency (Asset und Fiat verwechselt), 400 invalid_amount, 404 unknown_asset, 400 unsupported_fiat, 400 paid_btn_url_required sowie bei Anfragen mit Kursfestschreibung 400 rate_lock_fiat_only, 409 ratelock_disabled, 409 rate_unavailable (kein frischer Kurs für ein akzeptiertes Asset – wiederholen).

Wie Rechnungen bezahlt werden

Der Zahler zahlt aus dem Guthaben seiner Wallet in der Mini App – sofort und ohne Netzwerkgebühr. Ein Zahler kann die Rechnung auch aus einer externen Wallet finanzieren: Die App zeigt ihm eine Einzahlungsadresse, seine Übertragung landet in seiner eigenen Wallet, und die Rechnung wird automatisch beglichen, sobald sie ankommt. In beiden Fällen siehst du dasselbe: eine normale Rechnung mit paid und einen Webhook invoice_paid – es gibt keine zusätzlichen Parameter oder Felder zu behandeln.

Auf einer Fiat-Rechnung wird der Krypto-Betrag bei der Zahlung berechnet und zu deinen Gunsten aufgerundet, damit du nie weniger als den Fiat-Nennwert erhältst. Ist kein frischer Kurs verfügbar, schlägt die Zahlung auf der Seite des Zahlers fehl, statt zu einem veralteten Kurs abgerechnet zu werden.

Den Kurs auf einer Fiat-Rechnung festschreiben

Übergib rate_lock_seconds, um bei der Erstellung den aktuellen Kurs jedes akzeptierten Assets festzuhalten. Solange die Festschreibung gilt, sieht der Zahler genau die festgehaltenen Beträge, und die Zahlung wird zum festgehaltenen Kurs umgerechnet – du trägst für dieses Fenster das Kursrisiko. Der Server begrenzt das Fenster auf 60 Sekunden bis zum Plattformmaximum (derzeit 15 Minuten).

Läuft die Festschreibung ab, bleibt die Rechnung zahlbar und fällt still auf die Umrechnung zum Zahlungszeitpunkt zurück. Wenn die Rechnung mit dem Angebot enden soll, setze expires_in auf denselben Wert.

getInvoices

GET /pay/api/getInvoices – Berechtigung read. Filter: asset, fiat, invoice_ids (kommagetrennt), status (active / paid / expired – expired ist eine Erweiterung; active schließt Rechnungen aus, deren Frist bereits abgelaufen ist), dazu offset / count. Liefert {"items": [invoice, …]}, neueste zuerst.

deleteInvoice

POST /pay/api/deleteInvoice – Berechtigung invoices. Ein Parameter: invoice_id. Storniert eine unbezahlte Rechnung und liefert true. Fehler: 404 invoice_not_found, 409 invoice_already_paid – eine bezahlte Rechnung lässt sich nicht löschen, das Geld ist bereits bewegt worden.

refundInvoice

POST /pay/api/refundInvoice – Berechtigung refunds, Limit 30 pro Minute. Eine Erweiterung gegenüber Crypto Bot: erstattet den Nennbetrag einer bezahlten Rechnung – oder einen Teil davon – aus deinem App-Guthaben an den zurück, der sie bezahlt hat, auch an anonyme Zahler und ohne offenzulegen, wer sie waren.

Parameter	Typ	Pflicht	Bedeutung
invoice_id	integer	ja	die bezahlte Rechnung
amount	string	nein	der zu erstattende Betrag, im Asset der Rechnung. Weggelassen = der gesamte noch nicht erstattete Rest. Teilerstattungen summieren sich bis zum Nennbetrag
spend_id	string	nein	Idempotenzschlüssel – nutze einen, damit eine Wiederholung nach einem Timeout das Ergebnis wiedergibt, statt zweimal zu erstatten

Das Ergebnis ist das aktualisierte Rechnungsobjekt mit dem kumulierten refunded_amount / refunded_minor; refunded_at wird festgehalten, sobald die Rechnung vollständig erstattet ist. Der Status bleibt paid. Die Plattformgebühr wird nicht zurückgegeben. Jede Rückerstattung löst den optionalen Webhook refund_completed aus.

Fehler: 404 invoice_not_found, 409 invoice_not_paid, 409 already_refunded (es ist nichts mehr zu erstatten), 409 amount_too_big (mehr als der noch nicht erstattete Rest), 409 insufficient_funds, 400 invalid_amount und das spend_id-Paar 409 idempotency_conflict / 409 idempotency_in_progress.