Krypto-Zahlungen mit WordPress

WordPress hat keinen eingebauten Weg, Krypto zu akzeptieren, und Qvard hat noch kein fertiges WordPress-Plugin. Dafür gibt es eine einfache API, und WordPress kann sehr gut mit einer API arbeiten. Dieser Leitfaden zeigt, wie Sie einen WooCommerce-Shop mit zwei kleinen Code-Teilen an Qvard anbinden und was Sie prüfen, wenn es nicht funktioniert.

Plugin oder eigener Code: die ehrliche Wahl

Bei WordPress sucht man zuerst nach einem Plugin, und das ist ein naheliegender Reflex: installieren, Schlüssel einfügen, fertig. So ist die Lage heute.

Qvard hat noch kein WordPress- oder WooCommerce-Plugin. Die Integration läuft über die API. Das sagen wir lieber offen, als Sie nach einem Plugin suchen zu lassen, das es nicht gibt.
Drittanbieter-Plugins für andere Krypto-Gateways verbinden sich nicht mit Qvard. Jedes Plugin spricht mit der API seines eigenen Gateways.
Der eigene Weg ist überschaubar. Eine Anfrage erstellt eine Zahlung, ein Endpunkt empfängt das Ergebnis. Ein WordPress-Entwickler schreibt das in ein bis zwei Stunden, und Sie bestimmen genau, was mit der Bestellung geschieht.

Wenn Sie eine Einrichtung ohne Code wollen, ist Qvard noch nicht so weit. Wenn Sie einen Entwickler haben oder eine Stunde seiner Arbeitszeit bezahlen können, lesen Sie weiter.

Wie die Integration funktioniert

Der Ablauf einer WooCommerce-Bestellung:

An der Kasse wählt der Kunde „Mit Krypto bezahlen“. Ihr Code erstellt über die Qvard-API eine Zahlung und verwendet die WooCommerce-Bestellnummer als id der Zahlung.
Qvard liefert eine redirectUrl. Sie leiten den Kunden auf diese gehostete Seite weiter, wo er ein Asset und ein Netzwerk wählt und aus seiner eigenen Wallet zahlt.
Ist die Zahlung abgeschlossen, ruft Qvard einen Endpunkt auf Ihrer Seite auf.
Der Endpunkt findet die Bestellung über die id und markiert sie als bezahlt, sodass WooCommerce seine üblichen E-Mails versendet und die Bestellung in Bearbeitung setzt.

Ihre WordPress-Seite erzeugt nie Adressen und überwacht keine Blockchain. Die zwei Teile, die Sie schreiben, sind der Aufruf, der die Zahlung erstellt, und der Endpunkt, der das Ergebnis empfängt.

Teil 1: die Zahlung erstellen

Verwenden Sie in WordPress wp_remote_post, um https://api.qvard.com/api/v1/payment mit Ihrem API-Schlüssel im Header Authorization: Bearer und einem JSON aufzurufen: id (Ihre Bestellnummer als String) und price (der Betrag in US-Dollar). Ein erfolgreicher Aufruf liefert HTTP 201 mit einer redirectUrl.

Das Beispiel unten tut genau das für eine WooCommerce-Bestellung. Bewahren Sie den Schlüssel als Konstante in wp-config.php auf, nicht im Theme und nicht in den Datenbankoptionen, aus denen ihn Plugins und Exporte preisgeben können.

Zwei WooCommerce-Details sind wichtig:

Währung. Der Preis wird in US-Dollar gesendet. Nutzt Ihr Shop eine andere Währung, rechnen Sie die Bestellsumme vor dem Aufruf in Dollar um, sonst wird vom Kunden ein falscher Betrag verlangt.
Wiederholungen. Wird dieselbe id für dieselbe Zahlungsmethode erneut gesendet, kommt die bestehende Zahlung zurück; ein Doppelklick oder eine wiederholte Anfrage erzeugt also keine zweite.

Binden Sie das in eine eigene Zahlungsmethode oder in den Kassenschritt ein, der die Auswahl „Mit Krypto bezahlen“ verarbeitet, und leiten Sie den Kunden auf die zurückgegebene URL weiter.

PHPqvard-create-payment.php

<?php
// Create a Qvard payment for a WooCommerce order and return the page to send the customer to.
// QVARD_API_KEY is defined in wp-config.php, never in a theme or a public repository.
function qvard_create_payment( WC_Order $order ) {
    $response = wp_remote_post( 'https://api.qvard.com/api/v1/payment', array(
        'timeout' => 15,
        'headers' => array(
            'Authorization'    => 'Bearer ' . QVARD_API_KEY,
            'Content-Type' => 'application/json',
        ),
        'body'    => wp_json_encode( array(
            'id'    => (string) $order->get_id(),   // matched again in the webhook
            'price' => (float) $order->get_total(), // US dollars
        ) ),
    ) );

    if ( is_wp_error( $response ) || 201 !== wp_remote_retrieve_response_code( $response ) ) {
        return null;
    }

    $data = json_decode( wp_remote_retrieve_body( $response ), true );
    return isset( $data['redirectUrl'] ) ? $data['redirectUrl'] : null;
}

Teil 2: den Webhook empfangen

Registrieren Sie in WordPress eine REST-Route und speichern Sie deren Adresse in Ihrem Qvard-Projekt als Callback-URL, etwa https://your-site.com/wp-json/qvard/v1/webhook. Ist eine Zahlung abgeschlossen, sendet Qvard einen POST mit der von Ihnen übergebenen id und dem status der Zahlung im Header X-Qvard-Signature signiert.

Drei Regeln für den Endpunkt:

Prüfen Sie die Signatur. Kontrollieren Sie X-Qvard-Signature (HMAC-SHA256 mit Ihrem geheimen Schlüssel) mit dem SDK und weisen Sie alles ab, was nicht passt.
Markieren Sie die Bestellung nur bei completed als bezahlt. Ein auf Ihre Seite zurückgekehrter Kunde ist kein Zahlungsnachweis, und der Status partial bedeutet, dass er weniger als erforderlich gesendet hat.
Antworten Sie genau mit HTTP 200. Qvard wertet jeden anderen Status als Fehler und wiederholt die Zustellung (fünf Versuche in rund sechs Minuten), folgt aber keinen Weiterleitungen. Wegen der Wiederholungen muss der Handler gegen doppelte Ausführung sicher sein; is_paid() im Beispiel verhindert einen doppelten Abschluss.

Mehr zur Sicherheit unter Krypto-Zahlungs-Webhooks absichern.

PHPqvard-webhook.php

<?php
// Webhook endpoint: https://your-site.com/wp-json/qvard/v1/webhook
add_action( 'rest_api_init', function () {
    register_rest_route( 'qvard/v1', '/webhook', array(
        'methods'             => 'POST',
        'permission_callback' => '__return_true', // authenticated below by the X-Qvard-Signature header
        'callback'            => function ( WP_REST_Request $request ) {
            try {
                $payload = ( new Qvard\Qvard( QVARD_API_KEY ) )->webhooks->constructEvent( $request->get_body(), $request->get_header( 'x-qvard-signature' ), QVARD_API_KEY );
            } catch ( \Exception $e ) {
                return new WP_REST_Response( null, 401 );
            }
            $order   = wc_get_order( (int) ( $payload['id'] ?? 0 ) );

            if ( $order && 'completed' === ( $payload['status'] ?? '' ) && ! $order->is_paid() ) {
                $order->payment_complete();
            }

            return new WP_REST_Response( null, 200 ); // must be exactly 200
        },
    ) );
} );

Was bei WordPress meist schiefgeht

Die meisten gescheiterten Integrationen bei WordPress liegen an der Umgebung, nicht am Code:

Der Webhook kommt nie an. Ein Sicherheits-Plugin, eine Firewall oder eine „Demnächst“-Seite blockiert unbekannte POST-Anfragen. Erlauben Sie die Route und testen Sie sie von außerhalb Ihres Netzwerks.
Die Route liefert 404. Sprechende Permalinks sind deaktiviert oder die Plugin-Datei wird nicht geladen. Öffnen Sie die Route im Browser; 401 oder 405 bedeutet, sie existiert, 404 nicht.
Seiten-Cache. Stellen Sie sicher, dass Ihr Cache-Plugin und Ihr CDN Anfragen an /wp-json/ weder cachen noch umschreiben.
Die Bestellung wird doppelt als bezahlt markiert. Der Handler ist nicht idempotent. Prüfen Sie is_paid() vor dem Abschluss.
Falscher Betrag. Die Shop-Währung ist nicht der US-Dollar und es wurde nicht umgerechnet.
Langsame Antworten. Aufwendige Plugins, die am Bestellabschluss hängen, können Ihre Antwort verzögern. Antworten Sie schnell mit 200 und erledigen Sie langsame Arbeit danach.

Nach der Zahlung kehrt der Kunde von selbst auf Ihre Seite zurück, da Rücksprung-URLs noch nicht verfügbar sind. Geben Sie ihm eine Bestellseite, die den tatsächlichen Status zeigt, statt einer Dankeseite, die Erfolg voraussetzt.

Vor dem Livegang testen

Öffnen Sie eine Demo-Rechnung, um die Zahlungsseite zu sehen, die Ihr Kunde erhält. Dann:

Erstellen Sie aus einer Testbestellung eine Zahlung und prüfen Sie, dass Sie eine redirectUrl erhalten.
Zahlen Sie einen kleinen echten Betrag und bestätigen Sie, dass der Webhook eintrifft und die Bestellung als bezahlt markiert wird.
Lassen Sie den Endpunkt einmal fehlschlagen, prüfen Sie, dass Qvard die Zustellung wiederholt und die Bestellung nicht zweimal abgeschlossen wird.
Lassen Sie sich einen kleinen Betrag von Ihrem Guthaben auf Ihre Wallet auszahlen.

Eine separate Sandbox gibt es noch nicht, verwenden Sie also kleine echte Beträge. Die Endpunkte und Felder stehen in der Entwicklerdokumentation, und die Integrationsübersicht zeigt, was heute sonst noch angebunden ist.

Was der Betrieb kostet

Es gibt keine Abo-Gebühr. Pro Zahlung ist die Provision für Ihr Projekt individuell und beginnt laut Preisseite bei 1 % und kann bis auf 0,1 % sinken; die aktuellen Konditionen finden Sie unter Preise. Auszahlungen auf Ihre eigene Wallet kosten nur die Netzwerkgebühr. Eine Auszahlung auf ein Bankkonto in Fiat ist nicht verfügbar.

Die einzigen Kosten, die Sie einplanen sollten, sind Entwicklungszeit: einmalig ein geringer Aufwand, dazu etwas Wartung, wenn WordPress oder WooCommerce die Registrierung von Zahlungsmethoden ändern.

FAQ

Gibt es ein Qvard-Plugin für WordPress oder WooCommerce?

Noch nicht. Heute läuft die Integration über die API: Eine Anfrage erstellt eine Zahlung, ein Webhook empfängt das Ergebnis. Ein WordPress-Entwickler kann beides in ein bis zwei Stunden in einen Shop einbauen.

Kann ich ein Krypto-Plugin nutzen, das für ein anderes Gateway gebaut wurde?

Nein. Jedes Plugin spricht mit seinem eigenen Gateway und kann sich nicht mit Qvard verbinden. Sie brauchen eigenen Code, der die Qvard-API aufruft.

Die Preise in meinem Shop sind nicht in US-Dollar. Was tun?

Der Preis wird in US-Dollar an Qvard gesendet; rechnen Sie die Bestellsumme also vor dem Erstellen der Zahlung um. Der Kunde zahlt dann den Gegenwert im gewählten Asset zu einem Kurs, der für eine Stunde festgeschrieben ist.

Der Webhook erreicht meine Seite nicht. Warum?

Meist blockiert ein Sicherheits-Plugin, eine Firewall oder eine Wartungsseite die Anfrage, oder die REST-Route ist nicht registriert. Prüfen Sie, dass die Route von außerhalb Ihres Netzwerks antwortet und auf eine gültige Anfrage genau HTTP 200 liefert.