Paiements crypto sur WordPress

WordPress n'a pas de moyen intégré d'accepter la crypto, et Qvard n'a pas encore de plugin WordPress prêt à l'emploi. Ce qu'il a, c'est une API simple, et WordPress sait parfaitement dialoguer avec une API. Ce guide montre comment connecter une boutique WooCommerce à Qvard avec deux petits morceaux de code, et ce qu'il faut vérifier quand cela ne marche pas.

Plugin ou code sur mesure : le choix honnête

Sur WordPress, on cherche d'abord un plugin, et c'est un réflexe raisonnable : installer, coller une clé, terminé. Voici la situation aujourd'hui.

Qvard n'a pas encore de plugin WordPress ou WooCommerce. L'intégration passe par l'API. Nous préférons le dire plutôt que de vous envoyer chercher un plugin qui n'existe pas.
Les plugins tiers conçus pour d'autres passerelles crypto ne se connecteront pas à Qvard. Chaque plugin parle à l'API de sa propre passerelle.
La solution sur mesure est modeste. Une requête crée un paiement et un point de terminaison reçoit le résultat. Un développeur WordPress peut l'écrire en une ou deux heures, et vous contrôlez exactement ce qui arrive à la commande.

Si vous voulez une mise en place sans code, Qvard n'y est pas encore. Si vous avez un développeur, ou pouvez en payer une heure, lisez la suite.

Comment fonctionne l'intégration

Le flux d'une commande WooCommerce :

À la caisse, le client choisit « Payer en crypto ». Votre code crée un paiement via l'API Qvard, en utilisant le numéro de commande WooCommerce comme id du paiement.
Qvard renvoie un redirectUrl. Vous envoyez le client vers cette page hébergée, où il choisit un actif et un réseau et paie depuis son propre portefeuille.
Lorsque le paiement est terminé, Qvard appelle un point de terminaison de votre site.
Le point de terminaison retrouve la commande par l'id et la marque comme payée, ce qui permet à WooCommerce d'envoyer ses e-mails habituels et de passer la commande en traitement.

Votre site WordPress ne génère jamais d'adresses ni ne surveille la blockchain. Les deux morceaux que vous écrivez sont l'appel qui crée le paiement et le point de terminaison qui reçoit le résultat.

Morceau 1 : créer le paiement

Dans WordPress, utilisez wp_remote_post pour appeler https://api.qvard.com/api/v1/payment avec votre clé API dans l'en-tête Authorization: Bearer et un JSON : id (votre numéro de commande, sous forme de chaîne) et price (le montant en dollars américains). Un appel réussi renvoie HTTP 201 avec un redirectUrl.

L'exemple ci-dessous fait exactement cela pour une commande WooCommerce. Gardez la clé dans wp-config.php comme constante, pas dans le thème ni dans les options de la base de données, d'où des plugins ou des exports risquent de la divulguer.

Deux détails WooCommerce comptent :

Devise. Le prix est envoyé en dollars américains. Si votre boutique utilise une autre devise, convertissez le total de la commande en dollars avant l'appel, sinon le client se verra demander un mauvais montant.
Nouvelles tentatives. Envoyer le même id pour le même moyen de paiement renvoie le paiement existant ; un double clic ou une requête répétée ne crée donc pas de second paiement.

Branchez cela sur un moyen de paiement personnalisé, ou sur l'étape de caisse qui gère le choix « Payer en crypto », et redirigez le client vers l'URL renvoyée.

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;
}

Morceau 2 : recevoir le webhook

Enregistrez une route REST dans WordPress et sauvegardez son adresse dans votre projet Qvard comme callback URL, par exemple https://your-site.com/wp-json/qvard/v1/webhook. Lorsqu'un paiement est terminé, Qvard envoie un POST avec l'id que vous avez fourni et le status du paiement, signé dans l'en-tête X-Qvard-Signature.

Trois règles pour le point de terminaison :

Vérifiez la signature. Contrôlez X-Qvard-Signature (HMAC-SHA256 avec votre clé secrète) avec le SDK et rejetez tout ce qui ne correspond pas.
Marquez la commande comme payée uniquement sur completed. Un client revenu sur votre site n'est pas une preuve de paiement, et un statut partial signifie qu'il a envoyé moins que requis.
Répondez avec exactement HTTP 200. Qvard traite tout autre statut comme un échec et réessaie (cinq tentatives en environ six minutes), et ne suit pas les redirections. À cause des nouvelles tentatives, le gestionnaire doit pouvoir s'exécuter deux fois sans risque ; is_paid() dans l'exemple évite une double finalisation.

Plus de détails sur la sécurité dans comment sécuriser les webhooks de paiement crypto.

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
        },
    ) );
} );

Ce qui casse le plus souvent sur WordPress

La plupart des intégrations qui échouent sur WordPress viennent de l'environnement, pas du code :

Le webhook n'arrive jamais. Un plugin de sécurité, un pare-feu ou une page « bientôt disponible » bloque les requêtes POST inconnues. Autorisez la route et testez-la depuis l'extérieur de votre réseau.
La route renvoie 404. Les permaliens propres sont désactivés ou le fichier du plugin n'est pas chargé. Ouvrez la route dans un navigateur ; un 401 ou 405 signifie qu'elle existe, un 404 qu'elle n'existe pas.
Cache de pages. Assurez-vous que votre plugin de cache et votre CDN ne mettent pas en cache ni ne réécrivent les requêtes vers /wp-json/.
La commande est payée deux fois. Le gestionnaire n'est pas idempotent. Vérifiez is_paid() avant de finaliser.
Mauvais montant. La devise de la boutique n'est pas le dollar américain et aucune conversion n'a été faite.
Réponses lentes. Des plugins lourds accrochés à la finalisation de commande peuvent retarder votre réponse. Renvoyez 200 rapidement et faites le travail lent ensuite.

Après avoir payé, le client revient sur votre site de lui-même, puisque les URL de retour ne sont pas encore disponibles. Donnez-lui une page de commande qui affiche le statut réel plutôt qu'une page de remerciement qui suppose le succès.

Testez avant la mise en production

Ouvrez une facture de démonstration pour voir la page de paiement que recevra votre client. Ensuite :

Créez un paiement à partir d'une commande de test et vérifiez que vous recevez un redirectUrl.
Payez un petit montant réel et confirmez que le webhook arrive et que la commande est bien marquée comme payée.
Faites échouer votre point de terminaison une fois, vérifiez que Qvard réessaie et que la commande n'est pas finalisée deux fois.
Retirez un petit montant de votre solde vers votre portefeuille.

Il n'y a pas encore de sandbox séparé ; utilisez donc de petits montants réels. Les points de terminaison et les champs sont dans la documentation développeur, et l'aperçu des intégrations montre ce qui est connecté aujourd'hui.

Ce que cela coûte à faire tourner

Il n'y a pas d'abonnement. Par paiement, la commission est fixée individuellement pour votre projet et, selon la page des tarifs, part de 1 % et peut descendre jusqu'à 0,1 % ; voir les tarifs pour les conditions actuelles. Les retraits vers votre propre portefeuille ne coûtent que les frais de réseau. Le retrait vers un compte bancaire en monnaie fiat n'est pas disponible.

Le seul coût à prévoir est le temps de développement : un peu, une seule fois, puis un peu de maintenance quand WordPress ou WooCommerce modifie la façon d'enregistrer les moyens de paiement.

FAQ

Existe-t-il un plugin Qvard pour WordPress ou WooCommerce ?

Pas encore. Aujourd'hui l'intégration passe par l'API : une requête crée un paiement et un webhook reçoit le résultat. Un développeur WordPress peut ajouter les deux à une boutique en une ou deux heures.

Puis-je utiliser un plugin crypto conçu pour une autre passerelle ?

Non. Chaque plugin parle à sa propre passerelle et ne peut pas se connecter à Qvard. Il vous faut du code sur mesure qui appelle l'API Qvard.

Ma boutique n'est pas en dollars américains. Que faire ?

Le prix est envoyé à Qvard en dollars américains ; convertissez donc le total de la commande avant de créer le paiement. Le client paie ensuite l'équivalent dans l'actif qu'il choisit, à un taux fixé pendant une heure.

Le webhook n'atteint pas mon site. Pourquoi ?

Généralement un plugin de sécurité, un pare-feu ou une page de maintenance bloque la requête, ou la route REST n'est pas enregistrée. Vérifiez que la route répond depuis l'extérieur de votre réseau et qu'elle renvoie exactement HTTP 200 à une requête valide.