Anleitung zur Einrichtung von QryptoPay

QryptoPay ist eine self-hosted Krypto-Acquiring-Lösung zur automatischen Annahme von Kryptowährungszahlungen auf Ihrer Website. Das Modul lässt sich schnell integrieren: Sie können Zahlungslinks automatisch erstellen, diese an Ihre Kunden senden und Zahlungen direkt auf Ihre eigenen Krypto-Wallets empfangen.

Die gesamte Lösung wird auf Ihrem eigenen Server betrieben. Dadurch behalten Sie die volle Kontrolle über Ihre Gelder und profitieren von einem erhöhten Sicherheitsniveau.

Voraussetzungen für den Start

QryptoPay ist ein Modul der Verwaltungsoberfläche BeAdmin. Für den korrekten Betrieb des Dienstes benötigen Sie:

• einen Server mit installiertem BeAdmin-Panel (siehe Installationsanleitung);
• einen Domainnamen, der auf diesen Server verweist (z. B. qpay.mysite.com).

⚠️ Wichtig

Der Domainname wird als Adresse der Zahlungsseite verwendet, auf die Ihre Kunden zur Durchführung der Zahlung weitergeleitet werden. Diese Seite läuft auf demselben Server, auf dem QryptoPay installiert ist. Falls Sie noch keinen Domainnamen haben, können Sie diesen jederzeit später hinzufügen.

Schritt 1. Installation des Moduls

Für den korrekten Betrieb von QryptoPay müssen die folgenden Module installiert werden:

• DOCKER — zwingend erforderlich, da QryptoPay auf Docker-Containern basiert;
• NGINX — kann später installiert werden, ist jedoch erforderlich, um die Zahlungsseite bereitzustellen.

Um ein Modul zu installieren, öffnen Sie den entsprechenden Bereich im Seitenmenü und klicken Sie auf Installieren. Die Module müssen nacheinander installiert werden.

Nach der erfolgreichen Installation aller Abhängigkeiten kehren Sie zum QryptoPay-Modul zurück und starten dort die Installation des Moduls selbst.

Schritt 2. Erstellen eines Merchants

Nach der erfolgreichen Installation von QryptoPay erstellen Sie einen Merchant. Klicken Sie dazu auf Erstellen und vergeben Sie einen beliebigen Namen (dieser kann bei Bedarf später geändert werden).

Wenn das Modul NGINX bereits installiert ist und Sie über eine Domain für die Zahlungsseite verfügen, können Sie diese in den erweiterten Einstellungen angeben. In diesem Fall wird die Zahlungsseite automatisch zusammen mit dem Merchant erstellt.

Nach dem Erstellen des Merchants können Sie mit der weiteren Konfiguration fortfahren.

Jeder Merchant umfasst die folgenden Komponenten:

• zwei Terminals: ein Hauptterminal und ein Testterminal — sie werden zur Einrichtung und Überprüfung der Anbindung an Ihr Projekt verwendet;
• Bereich Kunden — zur Nachverfolgung von Zahlern (die angezeigten Daten hängen vom ausgewählten Terminal ab);
• Bereich Zahlungen — zur Anzeige und Analyse von Zahlungen (ebenfalls abhängig vom gewählten Terminal);
• Bereich Wallets — zur Konfiguration von Zahlungsmethoden und zum Empfang von Zahlungen (nur für das Hauptterminal verfügbar).

ℹ️ Hinweis

Für das Testterminal sind keine Wallets erforderlich, daher ist die Erstellung von Wallets dort nicht vorgesehen.

Für den produktiven Betrieb des Merchants müssen Sie Ihr Projekt mit einem Terminal verbinden und mindestens ein Wallet hinzufügen.

Schritt 3. Einrichtung der Integration

Das zentrale Element der Integration ist das Terminal. Jedes Terminal verfügt über die folgenden Parameter:

• ID — eine eindeutige Kennung;
• Token-Paar — ein öffentlicher und ein privater Token (zur Identifizierung von Zahlungen);
• Webhook — die URL Ihres Projekts, an die QryptoPay Benachrichtigungen über den Zahlungsstatus sendet;
• Webhook-Schlüssel — wird zur Autorisierung der Webhook-Benachrichtigungen verwendet.

⚠️ Wichtig

Der private Token muss sicher aufbewahrt werden. Wird er kompromittiert, können Dritte in die Zahlungslogik Ihres Projekts eingreifen. Aus diesem Grund speichert QryptoPay den privaten Token nach der Generierung nicht auf seiner Seite.

Bei Verlust oder Kompromittierung können Sie jederzeit ein neues Token-Paar generieren. Vergessen Sie dabei nicht, die Werte in Ihrem Projekt zu aktualisieren.

Der Webhook-Schlüssel ist weniger kritisch, sollte jedoch ebenfalls nicht an Dritte weitergegeben werden, um manipulierte Webhook-Benachrichtigungen zu vermeiden.

Wir empfehlen, die Integration zunächst mit dem Testterminal zu beginnen. Im Gegensatz zum Hauptterminal können Sie damit die korrekte Funktion der Integration prüfen, ohne tatsächlich Kryptowährungen zu übertragen.

Generieren Sie zunächst ein Token-Paar für das Testterminal und speichern Sie den privaten Token sicher ab.

Speichern Sie anschließend die Terminal-Parameter in den Umgebungsvariablen Ihres Projekts. Eine .env-Datei kann beispielsweise wie folgt aussehen:

TERMINAL_ID: <Terminal-ID>
PRIVATE_TOKEN: <generierter privater Token>
WEBHOOK_KEY: <Webhook-Schlüssel aus den Einstellungen>
PAYMENT_URL: <Domain der Zahlungsseite>

Anschließend müssen Sie in Ihrem Projekt eine Methode zur Generierung der Signatur für Zahlungsanfragen implementieren. Diese Funktion erzeugt auf Basis des privaten Tokens und der Terminal-ID eine eindeutige Signatur, die ohne zusätzliche Verschlüsselung sicher übertragen werden kann.

Beispiel einer Implementierung zur Signaturerzeugung (Pseudocode):

function generate_token(private_key_b64, terminal_uuid) -> string
  # Privaten Schlüssel von base64/base64url in einen Seed (Rohbytes) dekodieren
  seed := decode_base64_any(private_key_b64)

  # Eindeutigen Nonce erzeugen (typischerweise uuid4)
  nonce := uuid_v4()

  # Payload zusammenstellen (Pflichtfelder)
  payload := {
    ts: current_unix_time_seconds(),
    nonce: nonce,
    terminal_uuid: terminal_uuid
  }

  # Payload in eine deterministische (kanonische) Byte-Darstellung serialisieren
  payload_bytes := canonical_encode(payload)

  # Payload in ein transport-sicheres Format kodieren
  payload_part := base64url_no_padding(payload_bytes)

  # Payload-Repräsentation signieren (in diesem Schema wird payload_part signiert)
  signature_bytes := sign(seed, bytes(payload_part, ASCII))

  # Signatur kodieren
  signature_part := base64url_no_padding(signature_bytes)

  # Token-Format: "<payload_b64u>.<sig_b64u>"
  return payload_part + "." + signature_part
end

⚠️ Wichtig

Für die Generierung von public_token müssen drei Pflichtparameter übergeben werden: der aktuelle Zeitstempel, ein nonce (empfohlen: uuid4) und die Terminal-ID.

Der Zeitstempel wird zur Berechnung der Gültigkeitsdauer des Links verwendet (1 Stunde). Das nonce dient der Sicherheit und verhindert, dass aus demselben Link mehrere Zahlungsabsichten erzeugt werden (Spam-Schutz). Ohne die Terminal-ID kann QryptoPay die Zahlung nicht verarbeiten.

Als Nächstes benötigen Sie eine Methode zur Generierung des Zahlungslinks. Der Link hat das folgende Format und unterstützt diese Parameter:

https://qpay.mysite.com/?      // Domain Ihrer Zahlungsseite
    amount_usd=55.1&           // Betrag in USD, Format 00.00
    payment_mid=...&           // Transaktions-ID in Ihrem Projekt
    public_token=...&          // Signatur, erzeugt durch Ihre Signatur-Methode
    back_to_store_link=...&    // Link zurück zu Ihrer Website nach der Zahlung (optional mit Parametern)
    customer.id=...&           // Kunden-ID aus Ihrem System (erforderlich)
    customer.email=...&        // Kunden-E-Mail aus Ihrem System (optional, wird in QryptoPay angezeigt)
    metadata.any=any           // beliebige zusätzliche Parameter im Format metadata.key=value

⚠️ Wichtig

Der Zahlungslink verwendet ein nonce und ist nur einmal gültig. Sobald ein Kunde den Link öffnet, eine Währung auswählt und den Bezahlvorgang startet (Schaltfläche Weiter), können die Zahlungsparameter nicht mehr geändert werden. In diesem Fall muss der Kunde zu Ihrer Website zurückkehren und einen neuen Zahlungslink erstellen. Dieses Verhalten ist aus Sicherheitsgründen so vorgesehen.

⚠️ Wichtig

Wenn sich die E-Mail-Adresse eines Kunden ändert, findet QryptoPay den Kunden bei der nächsten Zahlung über die ID und überschreibt die E-Mail, falls sie abweicht. Die aktualisierte E-Mail wird auch auf bereits erstellte Zahlungen angewendet.

Der allgemeine Ablauf zur Erstellung eines Zahlungslinks sieht wie folgt aus:

• In Ihrem Projekt wird eine Zahlungsabsicht erstellt (z. B. eine Transaktion).
• Der zu zahlende Betrag wird in USD umgerechnet (QryptoPay akzeptiert als Eingabewährung ausschließlich USD).
• Es wird ein Zahlungslink mit den erforderlichen Parametern erzeugt und an den Kunden weitergegeben.

Anschließend führt der Kunde die Zahlung auf der Zahlungsseite aus und kann danach zurück zu Ihrem Shop wechseln. Die Benachrichtigung über eine erfolgreiche oder fehlgeschlagene Zahlung trifft mit Verzögerung in Ihrem Projekt ein, da Blockchain-Transaktionen erst Netzbestätigungen abwarten müssen. Typischerweise dauert das 5–10 Sekunden (Tron, USDT TRC-20) bis 10–30 Minuten (Bitcoin).

In diesem Schritt können Sie einen Zahlungslink erzeugen, ihn öffnen, eine Währung auswählen und die Zahlung starten. Wenn alles korrekt eingerichtet ist, erscheint die Zahlung in Ihrem QryptoPay-Merchant im Testterminal.

Schritt 4. Webhook einrichten

Nachdem der Kunde die Zahlung abgeschlossen hat, beginnt QryptoPay, die Blockchains nach der passenden Transaktion zu durchsuchen. Wenn die Zahlung exakt gemäß den Anweisungen auf der Zahlungsseite ausgeführt wurde, wird eine Benachrichtigung über die erfolgreiche Zahlung an Ihren Webhook gesendet.

Die Benachrichtigung wird als Objekt im folgenden Format gesendet:

{
  "payment_result": payment_result, // Zahlungsergebnis: success, mismatch, unexpected
  "amount_coins": str(coins),        // Betrag in Kryptowährung, Format 00.00
  "amount_fiat": str(amount_usd),    // Betrag in USD, Format 00.00
  "fiat_code": "USD",                // Fiat-Währungscode
  "coins_asset": "USDC",             // Asset: BTC, ETH, USDT, USDC usw.
  "coins_chain": "ETH",              // Netzwerk: BTC, ETH, TRX usw.
  "service_id": "qryptopay_pi_uuid", // interne Zahlungs-ID in QryptoPay
  "payment_mid": "string",           // Transaktions-ID in Ihrem Projekt
  "metadata": { "key1": value1, "key2": value2 },
  "customer": {
    "id": "your_id",                 // Kunden-ID in Ihrem System
    "email": "string"                // E-Mail des Kunden, null falls nicht übergeben
  }
}

Die erhaltenen Daten können Sie für die Nachverarbeitung der Zahlung verwenden. Einige Parameter werden unverändert zurückgegeben — zum Beispiel alle metadata-Werte, die über den Zahlungslink übergeben wurden.

⚠️ Wichtig

Wenn QryptoPay die E-Mail-Adresse eines Kunden bereits gespeichert hat, bei der nächsten Zahlung jedoch keine E-Mail übergeben wird, enthält der Webhook die in QryptoPay gespeicherte E-Mail.

Auf Ihrer Seite benötigen Sie anschließend eine Methode, um die Signatur eingehender Webhook-Benachrichtigungen zu prüfen. Zusammen mit dem Payload wird der Header TerminalPrivateKey: Token <base64url("uuid:token")> gesendet — er enthält das Signatur-Token, mit dem Sie die Gültigkeit der Nachricht verifizieren können.

Beispiel einer Implementierung (Pseudocode):

function decode_terminal_credentials(header_value) -> (terminal_uuid, webhook_token)
  # Den base64/base64url-Teil nach dem Präfix "Token " extrahieren
  encoded_part := trim(substring_after(header_value, "Token "))

  # base64/base64url in eine UTF-8-Zeichenkette dekodieren
  decoded_string := utf8_decode(decode_base64_any(encoded_part))

  # Erwartetes Format: "uuid:token"
  parts := split(decoded_string, ":", limit = 2)

  terminal_uuid := parts[0]
  webhook_token := parts[1]

  return (terminal_uuid, webhook_token)
end

Die Terminal-ID und der Webhook-Schlüssel werden verwendet, um Zahlungsbenachrichtigungen zu verifizieren, die an Ihren Webhook gesendet werden. Als Nächstes müssen Sie in Ihrem Projekt einen Handler implementieren, der eingehende Webhook-Benachrichtigungen korrekt verarbeitet. Es gibt drei mögliche Szenarien:

• success — die Zahlung war erfolgreich. In diesem Fall empfiehlt es sich, den Wert amount_fiat aus der Benachrichtigung vor der Finalisierung mit Ihrem intern erwarteten Betrag abzugleichen;
• mismatch — der Kunde hat zu wenig oder zu viel bezahlt;
• unexpected — der Kunde hat Geld an das Wallet gesendet, ohne zuvor einen Zahlungslink zu erzeugen.

Wie Sie die einzelnen Fälle behandeln, entscheiden Sie selbst. Beispielsweise können Sie bei mismatch den eingegangenen Betrag mit dem erwarteten vergleichen und den Kunden bei einer Unterzahlung über den fehlenden Betrag informieren. Bei unexpected ist es möglich, das Guthaben des Kunden automatisch zu aktualisieren und ihn anschließend über den Zahlungseingang zu benachrichtigen.

Nachdem der Handler umgesetzt ist, tragen Sie die Webhook-URL in den Einstellungen des Testterminals ein und wiederholen Sie den Zahlungsablauf: Erzeugen Sie einen neuen Zahlungslink und öffnen Sie ihn. Beim Testterminal wird die Zahlung sofort verarbeitet und die Benachrichtigung umgehend an den Webhook gesendet.

Wenn die Benachrichtigung in Ihrem Projekt erfolgreich ankommt, können Sie die Testintegration als abgeschlossen betrachten.

Schritt 5. Wallets einrichten

Um Zahlungen zu akzeptieren, müssen Sie Wallets für jede Kryptowährung hinzufügen, die Sie unterstützen möchten. Die Wallets werden in externen Diensten erstellt und anschließend mit ihren параметрами im QryptoPay-Modul hinterlegt.

Eine подробная Anleitung zum Hinzufügen und Konfigurieren von Wallets finden Sie unter diesem Link.

Schritt 6. Einrichtung des Hauptterminals

Nach dem Hinzufügen der Wallets können Sie Ihre Website auf den Betrieb mit dem Hauptterminal umstellen. Gehen Sie dazu wie folgt vor:

• generieren Sie ein neues Token-Paar für das Hauptterminal;
• bearbeiten Sie die Terminal-Einstellungen und tragen Sie die Webhook-Adresse ein;
• ersetzen Sie in der .env-Datei Ihres Projekts die Werte ID, PRIVATE_TOKEN und WEBHOOK_KEY durch die Daten des Hauptterminals.

Anschließend können Sie die Funktion des Terminals mit einer Testzahlung überprüfen. Bitte beachten Sie: In diesem Schritt ist eine echte Kryptowährungsüberweisung erforderlich — und zwar in der Währung, für die Sie ein Wallet hinzugefügt haben. Wir empfehlen, mit kleinen Beträgen zu beginnen.

Wenn alle Einstellungen korrekt vorgenommen wurden, wird die Zahlung erfolgreich in Ihrem Projekt verbucht.