API de paiement crypto pour les développeurs

L'API Qvard est volontairement petite. Trois routes couvrent tout le cycle : créer un paiement, vérifier qu'un moyen de paiement est disponible et envoyer un paiement sortant. Cette référence décrit chacune telle qu'elle fonctionne aujourd'hui, avec les erreurs que vous rencontrerez, et dit franchement ce que l'API n'a pas, pour que vous ne construisiez pas sur une fonction qui n'existe pas.

Ce que couvre l'API

L'API publique se trouve à https://api.qvard.com/api/v1 et comporte trois routes :

POST /payment : créer un paiement et obtenir l'adresse de la page de paiement hébergée.
GET /method/:id/info : vérifier si un moyen de paiement de votre projet est prêt à accepter des paiements.
POST /payout : envoyer un paiement sortant vers une adresse crypto.

Les résultats arrivent par webhook : Qvard appelle une URL que vous avez enregistrée dans votre projet lorsqu'un paiement est terminé. Il n'existe pas de route pour relire un paiement par son identifiant ; le webhook est donc le moyen de connaître l'issue. Tout le reste, comme l'espace client, les soldes et les paramètres, se fait dans l'interface web.

Authentification

Chaque requête porte la clé API de votre projet dans l'en-tête x-api-key. Il n'y a pas de jetons à renouveler ni d'OAuth. Une clé absente ou inconnue renvoie 401 avec le message error.wrong.api.key.

Traitez la clé comme un mot de passe : gardez-la côté serveur, dans une variable d'environnement ou un gestionnaire de secrets, et jamais dans du code front-end ni dans un dépôt public. C'est aussi cette clé que Qvard vous renvoie dans l'en-tête x-api-key du webhook ; une fuite touche donc les deux sens.

Créer un paiement

POST /api/v1/payment prend un corps JSON :

id (chaîne, obligatoire) : votre propre identifiant de commande ou de facture. Il revient dans le webhook.
price (nombre, obligatoire) : le montant en dollars américains. Le client paie l'équivalent dans l'actif et le réseau qu'il choisit.
paymentSystemId (nombre, facultatif) : un moyen de paiement de votre projet. Si vous le transmettez, la page de paiement s'ouvre avec cet actif et ce réseau sélectionnés.

La réponse est 201 avec deux champs : id, l'identifiant du paiement côté Qvard, et redirectUrl, l'adresse de la page de paiement hébergée, de la forme https://my.qvard.com/pay/<id>. Redirigez le client vers elle, ou placez le lien dans un e-mail.

L'appel est idempotent par identifiant et moyen de paiement : renvoyer le même id pour le même moyen renvoie le paiement existant au lieu d'en créer un second ; réessayer après un délai dépassé est donc sans risque. Notez que le code de statut est 201, pas 200.

curlcreate-payment.sh

curl -X POST https://api.qvard.com/api/v1/payment \
  -H "x-api-key: $QVARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "order-1042", "price": 49.9 }'

# 201 Created
# { "id": "6f1c2d3e-...", "redirectUrl": "https://my.qvard.com/pay/6f1c2d3e-..." }

# 401 { "message": "error.wrong.api.key" }
# 400 { "message": "Error validation", "errors": { "price": "..." } }

Erreurs

Les erreurs partagent une seule forme, un corps JSON avec un message :

400 : le corps a échoué à la validation. Le message est Error validation et un objet errors associe chaque champ à son premier problème, par exemple un id manquant ou un price qui n'est pas un nombre. Un montant inférieur au minimum du moyen de paiement choisi est rejeté de la même façon.
401 : l'en-tête x-api-key est absent ou inconnu (error.wrong.api.key).
404 : sur la route d'information du moyen de paiement, un identifiant de moyen qui n'existe pas (error.notfound).

Journalisez le corps complet de la réponse en cas de 4xx ; le message nomme le champ à corriger. Ne réessayez pas un 400 ou un 401 sans rien changer, mais réessayez un délai dépassé ou un 5xx, ce qui est sûr grâce à l'idempotence ci-dessus.

Statuts de paiement et webhook

Un paiement a l'un de quatre statuts : wait (créé, non payé), partial (moins que le montant complet est arrivé), completed (le montant complet est arrivé) et rejected.

Le webhook est envoyé lorsque le paiement est terminé : Qvard fait un POST vers la callback URL de votre projet avec un petit JSON contenant votre id et le status, et place votre clé API dans l'en-tête x-api-key. Votre point de terminaison doit répondre exactement HTTP 200 ; tout autre statut, un délai dépassé ou une redirection compte comme une livraison échouée et est réessayé, cinq tentatives au total en environ six minutes. L'en-tête est un en-tête d'authentification, pas une signature cryptographique ; comparez-le donc à votre clé en temps constant. Rendez le gestionnaire idempotent, car une livraison peut arriver deux fois.

Les détails, avec du code, sont dans comment sécuriser les webhooks de paiement crypto, et tout le flux est parcouru dans comment accepter les paiements crypto sur un site web.

Vérifier qu'un moyen de paiement est prêt

GET /api/v1/method/:id/info prend l'identifiant numérique d'un moyen de paiement de votre projet et répond 200 avec trois champs :

server : des détails sur l'état du moyen de paiement.
isReady : true lorsque le moyen est prêt à accepter un paiement.
isActive : true lorsque le moyen n'est pas hors ligne, même s'il est encore en train de rattraper le réseau.

Utilisez-le avant de proposer un actif et un réseau précis à la caisse, par exemple pour masquer un moyen temporairement indisponible. Un identifiant inconnu renvoie 404. C'est facultatif : si vous laissez le client choisir sur la page de paiement, vous n'en avez pas besoin.

Paiements sortants

POST /api/v1/payout envoie des fonds de votre solde vers une adresse crypto. Le corps JSON contient :

id (chaîne, obligatoire) : votre propre identifiant de paiement sortant, utilisé pour dédoublonner les nouvelles tentatives ; envoyer le même id deux fois ne paie donc pas deux fois.
price (nombre, obligatoire) : le montant dans la crypto du moyen de paiement, pas en dollars.
methodId (nombre, obligatoire) : le moyen de paiement de votre projet.
address (chaîne, obligatoire) : l'adresse de destination.
comment (chaîne, facultatif).

Un appel réussi renvoie 201. Les paiements sortants déplacent de l'argent réel ; testez donc avec un petit montant, revérifiez l'adresse et le réseau du moyen de paiement, et confirmez auprès de Qvard que les paiements sortants par API sont activés pour votre projet. Le retrait vers un compte bancaire en monnaie fiat n'est pas disponible ; un paiement sortant va vers une adresse crypto et ne coûte que les frais de réseau.

Ce que l'API n'a pas encore

Pour vous éviter de les chercher :

Aucun point de terminaison pour récupérer un paiement par identifiant ; appuyez-vous sur le webhook et sur vos propres enregistrements.
Aucune signature de webhook ; l'authentification est l'en-tête x-api-key.
Aucun sandbox : un environnement de test séparé figure sur la feuille de route ; utilisez donc de petits montants réels. Une facture de démonstration montre la page de paiement sans payer.
Aucune URL de retour après paiement : le client revient sur votre site de lui-même.
Aucun plugin prêt à l'emploi pour les plateformes de boutique, et les liens de paiement sont en développement.

Pour les formats et exemples, voir la documentation développeur. Pour les conditions commerciales, la page des tarifs.

FAQ

Dans quelle devise fixer le prix ?

En dollars américains. Le client paie l'équivalent dans l'actif et le réseau qu'il choisit sur la page de paiement, à un taux fixé pendant une heure. Le paiement sortant fait exception : son montant est dans la crypto du moyen de paiement.

Est-il sûr de réessayer la création d'un paiement ?

Oui. Envoyer le même id pour le même moyen de paiement renvoie le paiement existant ; réessayer après un délai dépassé ne crée donc pas de doublon.

Comment connaître l'issue d'un paiement ?

Par le webhook, envoyé lorsque le paiement est terminé. Il n'y a pas de route pour lire un paiement par son identifiant ; conservez donc l'id que vous envoyez et rapprochez-le à l'arrivée du webhook.

Y a-t-il un sandbox ?

Pas encore. Un environnement de test séparé est prévu. Pour l'instant, utilisez de petits montants réels et une facture de démonstration pour voir la page de paiement.