Cryptanio
Konto

Kryptozahlungen in einem Telegram-Bot annehmen

So verknüpfen Sie eine Bestellung für ein physisches Produkt in Ihrem eigenen Telegram-Bot mit einer Cryptanio-Rechnung, senden einen Zahlungslink und prüfen die Zahlung. Mit den Einschränkungen für Telegram Stars und Mini Apps.

Aktualisiert:

Eine Kryptozahlung lässt sich mit einer Bestellung in Ihrem eigenen Telegram-Bot verknüpfen: Der Server erstellt eine Cryptanio-Rechnung, der Bot sendet dem Käufer einen Link und meldet nach Prüfung der Zahlung die Annahme der Bestellung. Im Folgenden geht es um einen Shop für physische Produkte, zum Beispiel gedruckte Poster. Den Bot und die Bestellverarbeitung entwickeln Sie selbst.

Prüfen Sie zuerst die Regeln von Telegram

Für digitale Produkte und Dienstleistungen, die innerhalb von Telegram verkauft werden, sind Telegram Stars mit der Bezeichnung XTR vorgeschrieben. Das gilt beispielsweise für kostenpflichtigen Zugang zu Inhalten eines Bots. Ein Link auf eine externe Website begründet keine Ausnahme: Für einen solchen Kauf dürfen Sie Kryptowährungen nicht anstelle von Stars anbieten. Diese Einschränkungen sind ausdrücklich in der Dokumentation zu Telegram Stars beschrieben.

Unser Szenario betrifft einen normalen Bot ohne Mini App und die Bestellung eines physischen Produkts. Für Mini Apps und die mit ihnen verbundenen Bots gelten zusätzliche Einschränkungen für Blockchain-Integrationen, auch zur Nutzung von TON. Normale Bots ohne Mini App werden in den Blockchain Guidelines von Telegram ausdrücklich von diesen Regeln ausgenommen. Deshalb dürfen Sie diese Anleitung nicht ohne weitere Prüfung auf eine Mini App übertragen. Die Telegram-Regeln wurden am 13. November 2026 geprüft.

Was Sie benötigen

Bereiten Sie Ihren eigenen Bot, einen Server für dessen Betrieb, ein Cryptanio-Konto und ein Projekt mit aktivem Dienst Payments vor. Sie benötigen Empfangsadressen, die mit Payments dieses Projekts verbunden sind, sowie einen Live-API-Schlüssel mit Berechtigungen für Rechnungen und den benötigten Dienst.

Bewahren Sie den Token des Telegram-Bots, den Cryptanio-API-Schlüssel und das Geheimnis zur Prüfung des Webhooks auf dem Server auf. Der Käufer erhält nur seinen Zahlungslink. Dieses Szenario setzt keine fertige Integration voraus, die Ihren Shop selbst erstellt und die Bestellungen verarbeitet.

1. Bereiten Sie das Zahlungsprojekt vor

Aktivieren Sie Payments und fügen Sie die Empfangsadressen über die Kontooberfläche zum Adresspool des Dienstes hinzu. Ein Eintrag der Adresse nur im Adressbuch reicht nicht aus. Vergewissern Sie sich, dass das gewünschte Netzwerk und der Vermögenswert in Ihrem Projekt verfügbar sind; versprechen Sie dem Käufer keine Optionen, die auf der Zahlungsseite fehlen.

Wenn Ihnen der Unterschied zwischen USDT und dem Netzwerk noch nicht klar ist, lesen Sie zuerst „Netzwerk und Token“. Die Rechnung selbst verknüpft eine konkrete Zahlungsanforderung mit ihrem Status.

2. Verknüpfen Sie die Bestellung mit dem Käufer

Nachdem der Nutzer ein Poster ausgewählt und die Bestellung bestätigt hat, erstellt der Server eine interne Bestellnummer. Speichern Sie die Zuordnung zwischen Bestellung, Telegram-Käufer und der späteren Rechnungs-ID. Kontaktdaten und Lieferadresse bleiben in Ihrem eigenen System: Sie gehören weder in den technischen Link noch in eine öffentlich zugängliche Nachricht.

Eine Bestellung muss sich anhand der gespeicherten Rechnungs-ID eindeutig finden lassen. So können Sie die Zahlung auch nach einem Neustart des Bots verarbeiten.

3. Erstellen Sie eine eigene Rechnung

Rufen Sie die Rechnungserstellung über API v1 auf dem Server auf. Für das Szenario mit Auswahl von Netzwerk und Vermögenswert geben Sie den Bestellpreis über invoice_currency und invoice_amount an. USD 12.50 ist beispielsweise eine Preiseinheit; bezahlt wird mit einer unterstützten Kryptowährung. Das bedeutet weder die Annahme von Dollarzahlungen noch eine automatische Umwandlung der Mittel.

Unten steht ein Verweis auf das unterstützte Beispiel zur Erstellung einer Bestellung aus dem Dokumentationskatalog:

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
: "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}"
json_string() {
  local text="$1" char code index output='"'
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in
      '"'|'\') output+="\\$char" ;;
      *) printf -v code '%d' "'$char"
         if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi
         output+="$char" ;;
    esac
  done
  printf '%s"' "$output"
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"invoice_currency":"USD","invoice_amount":"12.50","reference":"order-42"}' \
  "https://api.cryptanio.com/v1/invoices" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

Beispiel herunterladen

Übergeben Sie die eigenen Parameter Ihrer Bestellung. Für einen neuen Vorgang ist ein eindeutiger Idempotency-Key erforderlich; wenn Sie dieselbe Anfrage nach einem Fehler wiederholen, behalten Sie den bisherigen Schlüssel bei. So soll ein erneuter Klick keine weitere Rechnung erzeugen. Einzelheiten finden Sie in der Anleitung zur Bestellbestätigung.

Speichern Sie checkout_url aus der Antwort auf die Erstellung und senden Sie die URL als Link-Schaltfläche im privaten Chat. Die Bot API unterstützt URL-Schaltflächen; dies ist unter InlineKeyboardButton beschrieben. Der Käufer öffnet die Cryptanio-Seite und wählt eine verfügbare Zahlungsmethode.

Übergeben Sie genau die erhaltene URL. Bauen Sie den Link nicht aus der ID zusammen: Der beim Lesen einer Rechnung zurückgegebene Link dient nur zur Ansicht. Die gespeicherte Antwort auf die Erstellung wird benötigt, um die interaktive Zahlung fortzusetzen.

5. Bestätigen Sie die Zahlung auf dem Server

Richten Sie den Webhook des Projekts auf Ihren Handler ein und prüfen Sie die Signatur anhand des unveränderten Request-Bodys. Ordnen Sie das Ereignis der gespeicherten Rechnung zu und prüfen Sie anschließend deren aktuellen Status über die API.

Geben Sie die Bestellung erst beim erfolgreichen Status paid zur Bearbeitung frei. Eine erkannte Transaktion, die Rückkehr des Käufers in den Chat und seine Nachricht „Ich habe bezahlt“ sind keine solche Bestätigung. Teilzahlungen, zu geringe, zu hohe oder verspätete Zahlungen können eine gesonderte Entscheidung erfordern; bestätigen Sie solche Bestellungen nicht automatisch. Ein erneut zugestellter Webhook darf die Ausführung der Bestellung nicht noch einmal auslösen.

So prüfen Sie den Ablauf und finden Fehler

Prüfen Sie den vollständigen Ablauf an einer eigenen Bestellung: Erstellung, Aufruf des Links, Zahlung, Statusänderung und Nachricht des Bots. Berücksichtigen Sie die Netzwerkgebühren; diese Art der Rechnungserstellung arbeitet mit realen Daten. Prüfen Sie außerdem einen erneuten Klick auf die Schaltfläche und eine wiederholte Ereigniszustellung.

Wenn die Mittel gesendet wurden, die Bestellung aber nicht bestätigt ist, vergleichen Sie Netzwerk, Vermögenswert, Zahlungsdaten und Transaktionsbestätigungen. Steht der Status bereits auf paid, suchen Sie den Fehler in der Zuordnung zwischen Bestellung und Rechnung sowie im Handler des Bots. Benachrichtigungen an den Inhaber in Telegram lassen sich anhand einer eigenen Anleitung einrichten; sie ersetzen für sich genommen nicht die serverseitige Prüfung der Bestellung.

Verwandte Artikel