Zahlungen mit Rechnungen annehmen

Mit einer Rechnung stellst du einem Telegram-Nutzer einen Betrag in Rechnung. Du erstellst sie über die API, schickst dem Zahler ihren Link, und der Betrag wird deinem App-Guthaben in dem Moment gutgeschrieben, in dem die Zahlung bestätigt ist.

Der Ablauf

1. Erstelle die Rechnung mit createInvoice und gib ein Asset und einen Betrag an (oder einen Fiat-Preis – siehe unten).
2. Schicke dem Zahler den Link aus der Antwort. Beim Öffnen landet er auf dem Bildschirm Rechnung bezahlen in der App.
3. Er bestätigt und zahlt aus seinem Guthaben – sofort und ohne Netzwerkgebühr. Ein Zahler ohne ausreichendes Guthaben kann die Rechnung aus einer externen Wallet finanzieren; sie wird automatisch beglichen, sobald seine Übertragung ankommt, und für dich sieht es gleich aus.
4. Du wirst benachrichtigt. Der Webhook invoice_paid wird ausgelöst und der Betrag landet in deinem App-Guthaben.
5. Liefere die Bestellung aus. Warte auf nichts weiter; die Zahlung ist ab diesem Punkt endgültig.

Wenn du lieber pollst, statt einen Webhook zu empfangen: getInvoices liefert deine Rechnungen mit ihrem aktuellen Status. Der Webhook ist der schnellere Weg – Polling ist die Rückfalllösung.

Preise in Fiat

Eine Rechnung kann in Krypto ausgepreist werden oder in einer Fiat-Währung mit einer Liste akzeptierter Assets. Der Zahler begleicht sie dann in dem akzeptierten Asset, das er besitzt, umgerechnet zum Kurs im Moment der Zahlung. Das ist die übliche Wahl für einen Shop, dessen Katalog in einer realen Währung geführt wird.

Wenn du lieber einen festen Preis nennen willst: rate_lock_seconds schreibt die Umrechnungskurse bei der Erstellung für ein begrenztes Zeitfenster fest – der Zahler sieht genau die festgeschriebenen Beträge, und du trägst für diese Minuten das Kursrisiko. Details in der Rechnungs-Referenz.

Du kannst außerdem swap_to setzen, damit eingehende Zahlungen beim Eingang in ein einziges Asset getauscht werden – praktisch, um dein Guthaben in einem Stablecoin zu halten, ohne die Tauschvorgänge selbst durchzuführen.

Nützliche Optionen für Rechnungen

• description – wird dem Zahler auf dem Bildschirm Rechnung bezahlen angezeigt.
• hidden_message – wird dem Zahler erst nach der Zahlung gezeigt. So lieferst du einen Code, einen Schlüssel oder einen Link ohne separaten Zustellweg.
• payload – dein eigener, undurchsichtiger String, der im Webhook zurückgegeben wird. Trage hier deine Bestell-ID ein.
• expires_in – eine Frist, nach der die Rechnung nicht mehr bezahlt werden kann.
• paid_btn_name / paid_btn_url – der Button, den der Zahler nach der Zahlung sieht, um ihn zurück zu deinem Bot, deinem Kanal oder deiner Artikelseite zu bringen.
• open_amount – kein fester Betrag; der Zahler gibt ihn bei der Zahlung ein. Die natürliche Form für Spenden und Trinkgelder.

Eine unbezahlte Rechnung kannst du mit deleteInvoice stornieren.

Rückerstattungen

refundInvoice erstattet den Nennbetrag einer bezahlten Rechnung – oder einen beliebigen Teil davon – aus deinem App-Guthaben an den zurück, der sie bezahlt hat, auch an anonyme Zahler und ohne offenzulegen, wer sie waren. Teilerstattungen summieren sich bis zum Nennbetrag; die Rechnung führt sie in refunded_amount. Übergib eine spend_id, damit eine Wiederholung nach einem Timeout das Ergebnis wiedergibt, statt zweimal zu erstatten. Die Plattformgebühr wird nicht erstattet.

⚠️ Prüfe die Webhook-Signatur, bevor du lieferst

Jeder kann per POST an deine Webhook-URL senden. Prüfe den Header TgPayCrypto-API-Signature – HMAC-SHA256 über den rohen Anfrage-Body, mit dem SHA-256 deines API-Tokens als Schlüssel –, bevor du eine Zahlung als echt behandelst, und dedupliziere anhand von update_id, damit eine Wiederholung die Bestellung nicht zweimal versendet.