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-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
Zeige einen Link oder eine Schaltfläche in deinem Bot. Der Nutzer öffnet die Rechnung und bezahlt aus seinem Wallet-Guthaben.
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. Über seine URL kann dein Agent die Dokumentation lesen, nach deiner Zustimmung eine Anwendung erstellen, den Webhook einrichten und Integrationscode schreiben. Du musst den Token nicht manuell kopieren.
- Schritt 1
Anweisung an den Agenten senden
Nutze Claude Code, claude.ai, Claude Desktop, ChatGPT oder einen anderen unterstützten MCP-Client. Die Anweisung findest du auch in der App 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
Einrichtung durch den Agenten abschließen
Der Agent erhält einen eingeschränkten Token und richtet Rechnungen, Abopläne und den Webhook ein. Den Signaturschlüssel für Webhooks verwaltest du in der App.
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 tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay 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, eingelösten Schecks, Rückerstattungen und Abos aktivierst du für jede Anwendung separat.
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
Gib deinem KI-Agenten die Adresse app.tgpaycrypto.com/mcp. Er kann die Anwendung anlegen, den Webhook einrichten und den Integrationscode schreiben. Die Erstellung genehmigst du im Bot.
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