Intégration API

Acceptez les paiements en cryptomonnaie depuis des portefeuilles crypto externes via la Merchant API.

Avec l’intégration API, votre application crée des factures crypto, affiche les instructions de paiement aux clients et suit le statut des paiements via l’API.

Vous pouvez utiliser l’API de deux façons :

• API seule : votre application construit toute l’expérience de paiement et affiche au client l’adresse crypto, le montant, le réseau et le délai d’expiration.
• API + Hosted Checkout : votre backend utilise l’API pour le suivi et le rapprochement des commandes, tandis que Hosted Checkout fournit la page de paiement côté client.

Quand choisir l’intégration API

Choisissez l’intégration API si vous voulez maîtriser le parcours de paiement sur votre propre site, application, bot ou agent IA.

L’intégration API est utile lorsque :

• Vous voulez créer votre propre interface de paiement.
• Vous devez créer des factures crypto de manière programmatique.
• Vous voulez afficher les instructions de paiement dans votre propre produit.
• Vous devez suivre le statut des paiements depuis votre backend.
• Vous voulez combiner Hosted Checkout et le rapprochement des commandes côté backend.

Pour l’intégration la plus rapide avec une page de paiement prête à l’emploi, utilisez plutôt l’intégration de Hosted Checkout.

Modèles d’intégration

Modèle	Expérience client	Rôle du backend	Gestion du statut
API seule	Créée par votre application	Créer la facture, afficher les informations de paiement, suivre le statut	Interroger régulièrement le statut du paiement via l’API
API + Hosted Checkout	Hébergée par Volet.com	Créer ou suivre les commandes, rapprocher le statut du paiement	Utiliser la Status URL de Hosted Checkout et la recherche de commande via l’API

Avant de commencer

Pour accepter des paiements crypto via l’API, vous avez besoin :

• D’un compte Volet.com vérifié.
• D’une API configurée dans la section Outils de paiement.
• Des autorisations API pour l’acceptation des paiements crypto.
• D’une configuration Hosted Checkout si vous utilisez l’API avec Hosted Checkout.

Consultez Créer une passerelle de paiement pour créer et configurer votre API.

Authentification

Les requêtes à la Merchant API nécessitent des en-têtes d’authentification.

Incluez les en-têtes suivants dans chaque requête API :

En-tête	Description
Api-Name	Nom de l’API configuré dans votre compte Volet.com.
Account-Email	Adresse e-mail du compte Volet.com propriétaire de l’API.
Authentication-Token	Jeton d’authentification de la requête, généré à partir du secret de votre API.

Gardez le secret de votre API confidentiel. N’exposez jamais les identifiants de l’API ni les jetons d’authentification dans le code frontend, les applications mobiles, les bots ou les scripts côté client.

Parcours API seule

Utilisez ce parcours lorsque votre application gère toute l’expérience de paiement crypto.

Le parcours de paiement :

1. Créez une commande dans votre système.
2. Si vous le souhaitez, vérifiez les informations de la facture avant de la créer.
3. Créez une facture crypto via l’API.
4. Affichez au client l’adresse de paiement, le montant, la devise, le réseau et le délai d’expiration.
5. Le client envoie le paiement depuis un portefeuille crypto.
6. Votre backend vérifie le statut du paiement via l’API.
7. Une fois le paiement effectué, mettez à jour le statut de la commande dans votre système.

Étape 1 : vérifier les informations de la facture

Avant de créer une facture, vous pouvez vérifier les valeurs calculées.

Cette étape vous permet de prévisualiser le montant de l’expéditeur, le montant du destinataire, la conversion de devise et le délai d’expiration avant de créer la facture réelle.

Point de terminaison :

POST /api/invoice/crypto-invoice/check

Exemple de requête :

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com"
}

Exemple de réponse :

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com",
  "senderAmount": 100,
  "receiverAmount": 100,
  "expirationDate": "2026-01-15T10:30:00",
  "expirationDateMillis": 1768473000000
}

Cette étape ne crée pas d’adresse de paiement et ne lance pas le paiement.

Étape 2 : créer une facture crypto

Créez une facture crypto lorsque le client est prêt à payer.

Point de terminaison :

POST /api/invoice/crypto-invoice/deposit

Exemple de requête :

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com"
}

La réponse renvoie les informations de paiement que votre application doit afficher au client.

Exemple de réponse :

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com",
  "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "addressOldFormat": null,
  "destinationTag": null,
  "senderAmount": 100,
  "receiverAmount": 100,
  "expirationDate": "2026-01-15T10:30:00",
  "expirationDateMillis": 1768473000000
}

Champs de la requête de facture

Champ	Obligatoire	Description
receiverCurrency	Oui	Devise créditée sur votre compte Volet.com une fois le paiement effectué.
senderCurrency	Oui	Devise et réseau que le client doit utiliser pour payer.
amount	Oui	Montant du paiement. Son interprétation dépend de transferAction.
transferAction	Oui	Indique si le montant correspond au montant à envoyer ou au montant à recevoir. Valeurs possibles : GIVE, GET.
note	Non	Note de paiement ou description de la commande.
sciName	Non	Nom du Hosted Checkout ou de la boutique associé au parcours de paiement.
orderId	Non	Identifiant interne de votre commande. Utilisez une valeur unique pour chaque paiement.
subMerchantURL	Non	URL du site du sous-marchand, si le paiement est traité pour le compte d’un autre marchand.

Champs de la réponse de facture

Champ	Description
address	Adresse crypto à laquelle le client doit envoyer le paiement.
addressOldFormat	Autre format d’adresse, s’il existe pour le réseau choisi.
destinationTag	Tag de destination, memo ou identifiant supplémentaire exigé par certains réseaux.
senderAmount	Montant que le client doit envoyer.
senderCurrency	Devise et réseau que le client doit utiliser.
receiverAmount	Montant attendu sur votre compte.
receiverCurrency	Devise créditée sur votre compte.
expirationDate	Date et heure d’expiration de la facture.
expirationDateMillis	Horodatage d’expiration de la facture en millisecondes.

Affichez toujours exactement senderAmount, senderCurrency, address et destinationTag s’il est renvoyé.

Étape 3 : afficher les instructions de paiement

En mode API seule, votre application doit afficher les instructions de paiement au client.

Affichez au minimum :

• Le montant à envoyer.
• La devise et le réseau blockchain.
• L’adresse crypto.
• Le tag de destination ou le memo, si nécessaire.
• Le délai d’expiration.
• Un avertissement indiquant d’envoyer les fonds uniquement sur le réseau sélectionné.

Exemple d’instruction :

Send exactly 100 USDT on Tron (TRC-20) to:

TXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This invoice expires at 2026-01-15 10:30 UTC.
Do not send funds on another network.

Pour les réseaux qui exigent un tag de destination ou un memo, affichez-le bien en évidence à côté de l’adresse.

Étape 4 : vérifier le statut du paiement

Après la création de la facture, votre backend doit vérifier le statut du paiement.

Point de terminaison :

GET /api/orders

Paramètre de requête obligatoire :

Paramètre	Description
orderId	Identifiant de commande du marchand.

Paramètre de requête facultatif :

Paramètre	Description
sciName	Nom du Hosted Checkout ou de la boutique associé à la commande.

Exemple de requête :

GET /api/orders?orderId=ORDER-1001&sciName=Store

Exemple de réponse :

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PROCESSING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:30:00",
  "transaction": {
    "status": "PROCESSING"
  },
  "invoice": {
    "invoiceStatus": "PROCESSING",
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

Statuts de paiement

Utilisez paymentStatus pour décider comment mettre à jour la commande dans votre système.

Statut	Signification	Action recommandée
CREATED	La facture a été créée et attend le paiement.	Laissez la commande en attente.
PROCESSING	Le paiement a été détecté ou est en cours de traitement.	Laissez la commande en attente et continuez à vérifier.
COMPLETED	Le paiement a été effectué avec succès.	Marquez la commande comme payée et livrez le produit ou le service.
FAILED	Le paiement a échoué, a expiré ou n’a pas pu aboutir.	Ne livrez pas la commande. Demandez au client d’effectuer un nouveau paiement.

Ne considérez la commande comme payée qu’une fois le statut passé à COMPLETED.

Parcours API + Hosted Checkout

Utilisez ce modèle si vous voulez confier la page de paiement côté client à Hosted Checkout, tout en gardant via l’API le contrôle du suivi et du rapprochement des commandes dans votre backend.

Le parcours de paiement :

1. Créez une commande dans votre système.
2. Redirigez le client vers Hosted Checkout via votre intégration Hosted Checkout.
3. Transmettez votre orderId dans la demande de paiement Hosted Checkout.
4. Le client effectue le paiement sur la page Hosted Checkout.
5. Volet.com envoie une notification de statut du paiement à votre Status URL.
6. Votre backend vérifie la signature de la notification.
7. Votre backend met à jour le statut de la commande.
8. Si vous le souhaitez, votre backend vérifie aussi la commande via l’API pour le rapprochement.

Dans ce modèle, Hosted Checkout gère la page de paiement, le choix du moyen de paiement, les instructions de paiement et les redirections du client.

L’API reste utilisable pour récupérer l’ordre de paiement par orderId et rapprocher le statut final dans votre système.

Gestion du statut avec Hosted Checkout

Avec Hosted Checkout, ne vous fiez pas uniquement aux redirections vers la Success URL ou la Failed URL.

Les redirections du client font partie du parcours dans le navigateur et n’atteignent pas toujours votre serveur. Utilisez la notification envoyée à la Status URL et la recherche de commande via l’API pour mettre à jour le statut des commandes de façon fiable.

Approche recommandée :

1. Recevez la notification Hosted Checkout sur la Status URL.
2. Vérifiez la signature de la notification.
3. Mettez à jour le statut de la commande si la notification est valide.
4. Utilisez la recherche de commande via l’API comme solution de repli ou contrôle de rapprochement.

Gestion des erreurs

Les erreurs de la Merchant API renvoient une réponse d’erreur structurée.

Cas d’erreur courants :

Statut HTTP	Signification
400	La requête est mal formée ou contient des paramètres non valides.
401	Les en-têtes d’authentification sont absents ou non valides.
403	L’API n’est pas autorisée à utiliser l’opération demandée.
404	La ressource demandée est introuvable.
500	Erreur serveur inattendue.

En cas d’erreur :

• Journalisez errorId pour le support et le diagnostic.
• Consultez errorField pour identifier le champ de la requête concerné.
• Ne créez pas automatiquement de commande en double.
• Ne réessayez que lorsque c’est sans risque.

Liste de contrôle des tests

Avant d’accepter des paiements crypto réels, testez le parcours complet.

Pour les intégrations API seule, vérifiez :

• La vérification de la facture.
• La création de la facture.
• L’affichage de l’adresse de paiement.
• L’affichage du tag de destination ou du memo, si nécessaire.
• La gestion de l’expiration de la facture.
• L’interrogation régulière du statut de la commande.
• La gestion des paiements effectués.
• La gestion des paiements échoués ou expirés.
• La gestion des orderId en double.

Pour les intégrations API + Hosted Checkout, vérifiez aussi :

• La redirection du client vers Hosted Checkout.
• La réception des notifications sur la Status URL.
• La validation de la signature des notifications.
• Les redirections vers la Success URL et la Failed URL.
• La recherche de commande via l’API pour le rapprochement.

Points importants

• Les intégrations API seule n’utilisent pas les callbacks de Hosted Checkout.
• Votre backend doit vérifier le statut du paiement via l’API.
• Utilisez toujours un orderId unique pour chaque paiement.
• Affichez toujours exactement l’adresse, le montant, la devise, le réseau et le tag de destination renvoyés par l’API.
• Ne marquez pas une commande comme payée tant que le statut du paiement n’est pas COMPLETED.
• Les paiements crypto dépendent des confirmations blockchain et de l’état du réseau.
• Envoyer des fonds à une mauvaise adresse ou sur un mauvais réseau peut entraîner leur perte définitive.

Voir aussi

• Créer une passerelle de paiement — créez et configurez votre API
• Accepter les paiements crypto dépositaires — fonctionnement des paiements crypto dépositaires
• Intégration de Hosted Checkout — utilisez la page de paiement hébergée
• Référence de l’API — documentation complète des méthodes, paramètres et réponses