Kryptozahlungen im Telegram-Bot: Rechnungen, Webhooks und Auszahlungen
Die Händler-API ist die Zahlungsschnittstelle von TgPay Crypto für Bots und Dienste. Erstelle eine Anwendung, erhalte einen Token, stelle Rechnungen per API aus und empfange signierte Zahlungs-Webhooks. Ein KI-Agent kann dich über den MCP-Server bei der Integration unterstützen. Zahlungen aus dem TgPay-Crypto-Guthaben werden intern verbucht, ohne Netzwerkgebühr oder Wartezeit auf Blockchain-Bestätigungen.
API-Basis: app.tgpaycrypto.com/pay/api · Testnet: testnet.tgpaycrypto.com
In vier Schritten vom Token zur ersten Zahlung
Erstelle eine Rechnung, zeige den Zahlungslink und verarbeite die Zahlungsbestätigung.
Anwendung erstellen
Öffne in der App „Mehr → Händler-API“ und lege eine Anwendung mit Namen und Webhook-URL an. Der Token wird einmal angezeigt. Bewahre ihn auf deinem Server auf.
Rechnung erstellen
Mit der POST-Anfrage createInvoice übermittelst du Betrag, Kryptowährung oder Fiatwährung, Beschreibung und Frist. Die Antwort enthält den Zahlungslink.
Link anzeigen
Über einen Button oder Link in deinem Bot bezahlt der Nutzer aus seinem Wallet-Guthaben. Größere Beträge bestätigt er mit PIN oder Face ID.
Webhook verarbeiten
Dein Server empfängt invoice_paid mit einer HMAC-SHA256-Signatur. Prüfe die Signatur, verhindere doppelte Verarbeitung anhand von update_id und liefere die Ware.
Integration mit Unterstützung deines KI-Agenten
Die Händler-API stellt einen MCP-Server bereit. Verbinde ihn in einem kompatiblen Agenten-Client: Der Agent kann die Dokumentation lesen, die Erstellung einer Anwendung anfragen, Webhooks einrichten und beim Integrationscode helfen. Du genehmigst die Anwendung in Telegram und prüfst und testest das Ergebnis.
- Schritt 1
Anweisung an den Agenten senden
Nutze einen Agenten-Client, in dem entfernte MCP-Server für dein Konto oder deinen Arbeitsbereich verfügbar sind. Die Anweisung findest du auch unter „Mehr → Händler-API → KI-Agent verbinden“.
- Schritt 2
Anwendung in Telegram genehmigen
Der Agent stellt einen t.me-Link bereit. Im Bot siehst du die angeforderten Schritte und genehmigst sie. Der Link gilt einmalig; vor deiner Zustimmung wird keine Anwendung erstellt.
- Schritt 3
Integration abschließen und testen
Der Agent erhält einen eingeschränkten Token und hilft beim Einrichten von Rechnungen, Aboplänen und Webhooks. Um den Signaturschlüssel für Webhooks zu erhalten, erneuere den Haupttoken in der App und speichere ihn sicher auf deinem Server.
Der über diesen Verbindungsablauf erteilte Token erlaubt das Annehmen von Zahlungen und die Webhook-Konfiguration. Überweisungen, Schecks und Rückerstattungen sind damit nicht freigegeben. Zusätzliche Auszahlungsberechtigungen erteilst und verwaltest du selbst.
Mehr zur Verbindung mit einem Agenten in der DokumentationConnect the MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
Füge in den Verbindungseinstellungen deines MCP-Clients app.tgpaycrypto.com/mcp als Server hinzu
https://testnet.tgpaycrypto.com/mcp
Gebühren und Limits
Die Werte stammen aus dem öffentlichen Limitkatalog zum Zeitpunkt der Erstellung dieser Seite. Maßgeblich sind die aktuellen Angaben in der App.
Funktionen der Händler-API
Eine Anwendung hat ein eigenes Guthaben, getrennt von deiner Wallet. Rechnungszahlungen erhöhen es; Auszahlungen und Schecks werden daraus finanziert.
Rechnungen und Rückerstattungen
Fester Kryptobetrag, Betrag in Fiatwährung oder freie Betragseingabe durch den Zahler. Vollständige und teilweise Rückerstattungen sind auch an anonyme Zahler möglich.
Abos
Der Nutzer stimmt dem Abo zu. Danach wird jeder Abrechnungszeitraum automatisch abgebucht; für jede Abbuchung gibt es ein Ereignis.
Überweisungen und Schecks
Sende Auszahlungen aus dem Anwendungsguthaben an Telegram-Nutzer oder erstelle Schecks zum Einlösen per Link.
Webhooks
invoice_paid wird immer gesendet. Ereignisse zu abgelaufenen Rechnungen und Schecks, Scheckeinlösungen, Rückerstattungen, Auszahlungen und Abos kannst du je App aktivieren.
Testnet
Die gleiche API und Mini-App stehen in @tgpaycrypto_testnet_bot bereit. Über die Schaltfläche auf der Startseite erhältst du einmal pro Stunde Test-Coins.
KI-Agent und MCP
Verbinde app.tgpaycrypto.com/mcp in einem Agenten-Client mit Unterstützung für entfernte MCP-Server. Nach deiner Zustimmung in Telegram kann der Agent eine Anwendung erstellen und bei der Integration helfen. Prüfe und teste das Ergebnis vor dem Einsatz.
Kompatibel mit der Crypto Bot API
Die Händler-API verwendet dieselben Methodennamen, das Antwortformat {ok, result} und das Signaturverfahren für Webhooks. Für die Umstellung änderst du Basis-URL und Token und prüfst die genutzten Methoden in der Dokumentation.
Token und Berechtigungen verwalten
Erstelle eingeschränkte Token mit festgelegten Berechtigungen, ersetze Token sofort und begrenze Auszahlungen auf gespeicherte Empfänger oder deaktiviere sie. Ein Tageslimit begrenzt den möglichen Schaden bei einem Token-Leck.
Häufige Fragen zur API
Informationen zu Token, Webhook-Signaturen, Tests und dem Wechsel von einer anderen API.
Je nach geltenden Regeln ist für die Erstellung einer Anwendung eine abgeschlossene Identitätsprüfung erforderlich. Wird sie angefordert, schließe die Verifizierung in der App ab und versuche es erneut.
Der Header TgPayCrypto-API-Signature enthält die HMAC-SHA256-Signatur des Anfrageinhalts. Als Schlüssel dient der SHA-256-Hash deines Haupttokens. Prüfe die Signatur anhand der unveränderten Bytes des Inhalts. Liefere erst nach erfolgreicher Prüfung und markiere die Rechnung vorher nicht als bezahlt.
Die Händler-API übernimmt Methodennamen, das Antwortformat {ok, result}, Beträge als Dezimalzeichenfolgen und das Signaturverfahren der Crypto Bot API. Passe Basis-URL und Token an und prüfe die verwendeten Methoden. Der Header Crypto-Pay-API-Token wird als Alias akzeptiert.
Im Testnet stehen dieselbe API und Mini-App bereit: Bot @tgpaycrypto_testnet_bot, API-Basis testnet.tgpaycrypto.com/pay/api. Über „Test-Coins holen“ auf der Startseite erhältst du einmal pro Stunde 1.000 USDT, 1.000 GRAM und 0,01 BTC. Mainnet- und Testnet-Token sind nicht austauschbar.
Mit einem eingeschränkten Token kann der Agent im Rahmen seiner Berechtigungen Rechnungen und Abopläne erstellen, Guthaben und Statistiken abrufen und den Webhook einrichten. Überweisungen, Schecks und Rückerstattungen erfordern entsprechende Auszahlungsberechtigungen und freigegebene Funktionen. Du bestimmst, welche Rechte du erteilst.
Öffentliche Dokumentation der Händler-API
Methodenreferenz, OpenAPI-Spezifikation und Anleitungen auf docs.tgpaycrypto.com.
Zahlungen in dein Produkt integrieren
Erstelle eine Anwendung in @tgpaycryptobot. Alternativ gibst du deinem KI-Agenten den MCP-Link und genehmigst die Erstellung im Bot.
Bot öffnen