Zahlungen mit Rechnungen annehmen

Mit einer Rechnung forderst du einen Telegram-Nutzer zur Zahlung auf. Du erstellst sie über die API und schickst dem Zahler ihren Link. Eine erfolgreiche Zahlung wird deinem App-Guthaben abzüglich der Händlergebühr gutgeschrieben.

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, wenn diese Option angeboten wird. Für die automatische Zahlung muss vor Ablauf der Zahlungsfrist genügend Guthaben gutgeschrieben sein und es darf keine Einschränkung ausgehender Zahlungen bestehen. Eine Einzahlung allein beweist keine Rechnungszahlung.
4. Du wirst benachrichtigt. Ist eine Webhook-URL eingerichtet, wird nach der Zahlung ein Ereignis invoice_paid zum Versand vorgemerkt. Deine App erhält den Betrag abzüglich der Gebühr.
5. Liefere die Bestellung aus. Prüfe zuerst die Webhook-Signatur, ordne die Rechnung deiner Bestellung zu und bestätige den Status paid. Du kannst ihn auch mit getInvoices prüfen. Weitere Blockchain-Bestätigungen sind nicht nötig.

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

Der Preis einer Rechnung kann in Krypto angegeben 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 Katalogpreise in einer Landeswährung angegeben sind.

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, um eingehende Zahlungen in ein einziges Asset umzutauschen, wenn der Tausch möglich ist. Lässt er sich nicht ausführen, gelingt die Zahlung trotzdem im ursprünglichen Asset. Prüfe is_swapped und die Felder swapped_*.

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 – ein eigener String, den die API unverändert im Webhook zurückgibt. 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. Geeignet für Spenden und Trinkgelder.

Beschreibung, versteckte Inhalte und der Button nach der Zahlung können verborgen bleiben, bis die Inhalte freigegeben sind. Verlasse dich nicht darauf, dass sie sofort nach dem Erstellen für Zahlende sichtbar sind.

Eine unbezahlte Rechnung kannst du mit deleteInvoice stornieren.

Rückerstattungen

refundInvoice erstattet die tatsächlich gezahlte Krypto – oder einen beliebigen Teil davon – aus deinem App-Guthaben an den Zahler, auch bei anonymer Zahlung und ohne dessen Identität offenzulegen. Teilerstattungen summieren sich höchstens bis zum ursprünglich gezahlten Kryptobetrag; die Rechnung führt sie in refunded_amount. Bei Fiatrechnungen gelten paid_asset und paid_amount, nicht der Fiat-Nennwert. Deine App braucht genügend Guthaben im ursprünglichen Zahlungsasset, auch nach einem automatischen Tausch. Übergib eine spend_id, damit eine Wiederholung nach einem Timeout das vorhandene Ergebnis liefert, 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 Haupt-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.