Aller au contenu principal

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 ou les notifications envoyées à la Status URL.

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

  • API seule avec interrogation du statut : votre application construit toute l’expérience de paiement et vérifie le statut du paiement via l’API.

  • API seule avec notifications à la Status URL : votre application construit toute l’expérience de paiement, et une configuration Hosted Checkout fournit la Status URL qui reçoit les notifications de paiement. La page Hosted Checkout elle-même n’est pas utilisée.

  • 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 recevoir les notifications de statut des paiements sur votre serveur.
  • 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èleExpérience clientRôle du backendGestion du statut
API seule + interrogationCréée par votre applicationCréer la facture, afficher les informations de paiement, suivre le statutInterroger GET /api/orders
API seule + Status URLCréée par votre applicationCréer la facture, afficher les informations de paiement, traiter les notificationsStatus URL de Hosted Checkout, avec recherche via l’API pour le rapprochement
API + Hosted CheckoutHébergée par Volet.comSuivre les commandes et rapprocher le statut des paiementsStatus URL de Hosted Checkout, avec recherche via l’API pour le rapprochement

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 suivantes :
    • Effectuer des transactions → Accepter les paiements crypto : pour créer des factures crypto.
    • Rechercher une transaction : pour récupérer les commandes de paiement.
  • D’une configuration Hosted Checkout dont vous pouvez transmettre le nom dans sciName.

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

Exigence actuelle concernant sciName

L’implémentation actuelle de GET /api/orders exige un nom de Hosted Checkout (sciName) pour récupérer une commande.

Tant que cette exigence n’est pas levée, créez une configuration Hosted Checkout et transmettez son nom dans sciName lorsque vous créez les factures crypto à suivre.

Vous n’avez pas besoin de rediriger les clients vers la page Hosted Checkout. La configuration peut servir uniquement à fournir le sciName requis et, si vous le souhaitez, les notifications à la Status URL.

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êteDescription
Api-NameNom de l’API configuré dans votre compte Volet.com.
Account-EmailAdresse e-mail du compte Volet.com propriétaire de l’API.
Authentication-TokenJeton SHA-256 généré à partir de password:YYYYMMDD:HH (UTC), où le mot de passe est celui défini dans votre compte Volet.com, sous Outils de paiement.

Par exemple :

SHA256("MySecret123:20261026:14")

donne :

c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd

La valeur du jeton change toutes les heures UTC. Générez un nouveau jeton juste avant chaque requête pour ne pas réutiliser un jeton généré pendant l’heure précédente.

Seul le jeton généré est envoyé à l’API. N’envoyez jamais le mot de passe de votre API.

Gardez le mot de passe 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.

Exemple de requête authentifiée :

curl -X POST https://api.volet.com/api/invoice/crypto-invoice/deposit \
-H "Content-Type: application/json" \
-H "Api-Name: my-store-api" \
-H "Account-Email: [email protected]" \
-H "Authentication-Token: c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd" \
-d '{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"sciName": "Store",
"orderId": "ORDER-1001"
}'

Parcours de paiement API seule​

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

  1. Créez une commande dans votre système.
  2. Si vous le souhaitez, vérifiez les informations calculées de la facture.
  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. Suivez le paiement via GET /api/orders, les notifications à la Status URL, ou les deux.
  7. Une fois le paiement effectué, mettez à jour le statut de la commande dans votre système.

Étape 1 (facultative) : 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

Consultez Vérification d’une facture crypto dans la référence de l’API.

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

Consultez Création d’une facture crypto de recharge dans la référence de l’API.

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
}

Les montants de ces exemples sont donnés à titre indicatif. Les valeurs réelles de senderAmount et receiverAmount dépendent des devises choisies, du taux de change et des frais applicables.

Champs de la requête de facture​

ChampObligatoireDescription
receiverCurrencyOuiDevise créditée sur votre compte Volet.com une fois le paiement effectué. Consultez les valeurs prises en charge dans la référence de l’API.
senderCurrencyOuiDevise et réseau que le client doit utiliser pour payer, par exemple USDT_TRC20.
amountOuiMontant du paiement. Son interprétation dépend de transferAction.
transferActionOuiIndique à quelle partie se rapporte amount. Valeurs possibles : GIVE, GET. Voir GIVE et GET.
noteNonNote de paiement ou description de la commande. Jusqu’à 255 caractères.
sciNameNon*Nom du Hosted Checkout défini dans votre compte Volet.com. Actuellement obligatoire si vous voulez récupérer la commande via GET /api/orders ou recevoir des notifications à la Status URL via la configuration Hosted Checkout.
orderIdNon*Identifiant interne de votre commande, jusqu’à 64 caractères. Nécessaire pour récupérer le paiement plus tard avec GET /api/orders. Utilisez une valeur unique pour chaque paiement.
subMerchantURLNonURL du site du sous-marchand, si le paiement est traité pour le compte d’un autre marchand. Voir Sous-marchands.

* Le point de terminaison de création de facture peut accepter ce champ comme facultatif, mais il est obligatoire pour les parcours de suivi décrits dans ce guide.

GIVE et GET​

transferAction détermine dans quelle devise est exprimé le amount de la requête.

ValeurSignification de amount
GIVELe montant envoyé par le client, exprimé en senderCurrency.
GETLe montant à créditer sur votre compte Volet.com, exprimé en receiverCurrency.

Les valeurs finales de senderAmount et receiverAmount renvoyées par l’API peuvent différer en raison des taux de change et des frais applicables.

Codes de devise​

Certains codes de cryptomonnaie incluent le réseau blockchain après un tiret bas.

Par exemple :

  • USDT_TRC20 : USDT sur Tron.
  • USDT_ERC20 : USDT sur Ethereum.
  • USDC_SOL : USDC sur Solana.

Les autres actifs utilisent un code de devise unique, comme BTC, ETH ou TON.

Consultez les valeurs acceptées dans Devises et tokens pris en charge et dans la référence de l’API.

Champs de la réponse de facture​

ChampDescription
addressAdresse crypto à laquelle le client doit envoyer le paiement.
addressOldFormatAutre format d’adresse, s’il existe pour le réseau choisi.
destinationTagTag de destination, memo ou identifiant supplémentaire exigé par certains réseaux.
senderAmountMontant que le client doit envoyer.
senderCurrencyDevise et réseau que le client doit utiliser.
receiverAmountMontant attendu sur votre compte.
receiverCurrencyDevise attendue sur votre compte.
expirationDateDate et heure d’expiration de la facture.
expirationDateMillisExpiration de la facture sous forme d’horodatage Unix en millisecondes.

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

Utilisez expirationDateMillis pour calculer et afficher l’expiration de la facture.

É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 :

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 peut récupérer la commande de paiement via l’API.

Point de terminaison :

GET /api/orders

Consultez Récupération d’une commande de paiement dans la référence de l’API.

Paramètres de requête actuels :

ParamètreObligatoireDescription
orderIdOuiIdentifiant de commande du marchand, jusqu’à 64 caractères.
sciNameOui*Nom du Hosted Checkout associé à la facture.

* sciName est actuellement exigé par l’implémentation de l’API pour récupérer une commande.

Exemple de requête :

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

Pour le moment, une commande créée via l’API ne peut pas être récupérée de façon fiable avec le seul orderId.

Créez une configuration Hosted Checkout, utilisez son nom comme sciName lors de la création de la facture crypto et transmettez la même valeur à GET /api/orders.

Vous pouvez utiliser cette solution sans afficher la page Hosted Checkout au client.

Exemple de réponse :

{
"orderId": "ORDER-1001",
"sciName": "Store",
"paymentStatus": "PENDING",
"paymentMethod": "CRYPTO_INVOICE",
"paymentCreated": "2026-01-15T10:00:00",
"transaction": {
"id": "11111111-1111-4111-8111-111111111111",
"status": "PENDING",
"senderAmount": 100,
"senderCurrency": "USDT_TRC20",
"receiverAmount": 100,
"receiverCurrency": "USD",
"created": "2026-01-15T10:00:00"
},
"invoice": {
"created": "2026-01-15T10:00:00",
"received": "2026-01-15T10:12:00",
"invoiceStatus": "RECEIVED",
"externalStatus": "PAYMENT_RECEIVED",
"penalties": [],
"cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"initialSenderAmount": 100,
"actualReceivedAmount": 100,
"senderCurrency": "USDT_TRC20",
"cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
}
}

Si aucune commande correspondante n’est trouvée, l’API peut renvoyer 404. Vérifiez orderId et sciName avant de créer une autre facture pour la même commande.

Statut du paiement​

Utilisez le paymentStatus de premier niveau pour savoir si le paiement est effectué.

StatutSignificationAction recommandée
PENDINGLe paiement n’a pas encore atteint un état final effectué.Laissez la commande en attente.
COMPLETEDLe paiement a été effectué avec succès.Marquez la commande comme payée et livrez le produit ou le service.
CANCELEDLe paiement a été annulé.N’exécutez pas la commande.
REFUNDEDLe paiement a été remboursé.Mettez à jour la commande selon votre processus de remboursement.

Ne considérez une commande comme payée que lorsque paymentStatus vaut COMPLETED.

La réponse contient aussi des champs propres à la facture, comme invoiceStatus, externalStatus et penalties. Ils peuvent apporter des informations supplémentaires sur la facture crypto.

Ne déduisez pas le statut final de la commande de valeurs non documentées de externalStatus ou penalties. Ne les utilisez que si votre intégration traite explicitement les valeurs renvoyées par l’API.

cryptoCurrencyTransactionId est l’identifiant de la transaction crypto renvoyé par l’API. Ne supposez pas qu’il s’agit d’un hash de transaction blockchain tant que ce n’est pas confirmé pour le parcours de paiement choisi.

Recevoir les notifications à la Status URL​

Interroger GET /api/orders n’est pas le seul moyen de suivre les factures crypto créées via l’API.

Pour le moment, la configuration de l’API dans votre compte Volet.com ne propose pas de champs pour des URL de webhook. Vous pouvez toutefois utiliser la Status URL configurée pour une passerelle Hosted Checkout afin de recevoir les notifications de statut des paiements pour les factures créées via l’API.

Dans ce parcours, vous n’avez pas besoin d’afficher Hosted Checkout ni d’y rediriger les clients.

Configurer les notifications à la Status URL​

  1. Créez une configuration Hosted Checkout dans votre compte Volet.com.
  2. Configurez sa Status URL et choisissez la méthode HTTP voulue.
  3. Utilisez le nom du Hosted Checkout comme sciName lors de la création de factures crypto via l’API.
  4. Gardez le parcours de paiement côté client dans votre propre application.
  5. Lorsque le statut du paiement change, Volet.com envoie une notification à la Status URL configurée pour ce Hosted Checkout.
  6. Vérifiez la signature de la notification avant de mettre à jour la commande dans votre système.
  7. Utilisez GET /api/orders comme contrôle de rapprochement ou solution de repli si nécessaire.

Exemple de requête de facture :

{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001"
}

Dans cet exemple, Store est le nom de la configuration Hosted Checkout qui contient la Status URL.

Le client voit toujours votre propre interface de paiement. La page de paiement Hosted Checkout ne s’ouvre pas.

remarque

Dans une intégration API seule, le même sciName remplit donc deux rôles :

  • Il permet à l’implémentation actuelle de GET /api/orders de trouver la commande.
  • Il relie la facture créée via l’API à la configuration Hosted Checkout utilisée pour les notifications à la Status URL.

Pour les paramètres des notifications et la vérification de la signature, consultez Intégration de Hosted Checkout.

Interrogation et notifications à la Status URL​

Vous pouvez utiliser :

  • L’interrogation de l’API.
  • Les notifications à la Status URL.
  • Les deux à la fois.

Pour les intégrations qui utilisent les notifications à la Status URL, la recherche via l’API sert au rapprochement si une notification arrive en retard ou si votre point de terminaison est temporairement indisponible.

Ne créez pas de facture en double simplement parce qu’une requête de statut ou la livraison d’une notification a échoué.

Parcours API + Hosted Checkout​

Utilisez ce modèle si vous voulez que Hosted Checkout lui-même fournisse la page de paiement côté client, tandis que votre backend utilise l’API pour le suivi et le rapprochement.

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 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.
  • Les redirections du client.

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

Gestion du statut avec Hosted Checkout​

Si vous utilisez la page 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 pour mettre à jour la commande dans votre backend, et la recherche de commande via l’API pour le rapprochement si nécessaire.

Approche recommandée :

  1. Recevez la notification Hosted Checkout sur la Status URL.
  2. Vérifiez la signature de la notification.
  3. Mettez à jour la commande si la notification est valide.
  4. Utilisez GET /api/orders comme solution de repli ou contrôle de rapprochement.

Consultez Intégration de Hosted Checkout pour le contenu des notifications et les règles de vérification de la signature.

Gestion des erreurs​

Les erreurs de la Merchant API utilisent une réponse structurée contenant une ou plusieurs erreurs dans data.errors.

Exemple de structure :

{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}

Champs de l’erreur :

ChampDescription
errorMessageCode d’erreur lisible par une machine renvoyé par l’API.
errorTypeCatégorie de l’erreur.
errorIdIdentifiant de l’erreur, à inclure dans les journaux et les demandes au support.
errorDescriptionDescription de l’erreur lisible par un humain.
errorFieldChamp de la requête concerné par l’erreur, s’il est disponible.
paramsParamètres supplémentaires associés à l’erreur, s’ils sont disponibles.
requestParamsParamètres de la requête associés à l’erreur, s’ils sont disponibles.

Réponses HTTP courantes :

Statut HTTPSignification
400La requête est mal formée ou contient des paramètres non valides.
401Les en-têtes d’authentification sont absents ou non valides.
404La ressource demandée est introuvable.
500Erreur serveur inattendue.

Les valeurs exactes de errorMessage dépendent du point de terminaison et de l’erreur. Ne déduisez pas un code d’erreur applicatif du seul statut HTTP.

En cas d’erreur :

  • Journalisez errorId pour le support et le diagnostic.
  • Consultez errorField s’il est disponible.
  • Dans le traitement programmatique des erreurs, utilisez errorMessage plutôt que errorDescription.
  • Ne créez pas automatiquement de facture en double après l’échec d’une requête au résultat incertain.
  • Ne réessayez que lorsque c’est sans risque.

Tests et sandbox​

Volet.com ne propose pas actuellement de sandbox ni d’environnement de préproduction pour tester les intégrations.

Si vous utilisez Hosted Checkout, vous pouvez prévisualiser la page de paiement côté client sur la page Hosted Checkout pour les développeurs. Cet aperçu n’est pas une sandbox et ne remplace pas les tests d’intégration.

Pour une présentation de l’API, de Hosted Checkout et du parcours de paiement avant la mise en production, contactez l’équipe commerciale de Volet.com.

Liste de contrôle des tests​

Avant d’accepter des paiements crypto réels, vérifiez le parcours complet utilisé par votre intégration.

Pour les intégrations API seule :

  • La vérification de la facture, si elle est utilisée.
  • La création de la facture.
  • L’affichage correct de l’adresse de paiement.
  • L’affichage du tag de destination ou du memo, si nécessaire.
  • L’affichage correct de la devise et du réseau.
  • La gestion de l’expiration de la facture.
  • La conservation de orderId et sciName.
  • La recherche de commande via GET /api/orders.
  • La gestion des paiements effectués.
  • La gestion des paiements annulés et remboursés.
  • La gestion des orderId en double.
  • La gestion des erreurs de l’API.

Si vous utilisez les notifications à la Status URL :

  • La configuration Hosted Checkout contient la bonne Status URL.
  • Le même nom de Hosted Checkout est transmis dans sciName.
  • Les notifications parviennent à votre backend.
  • Les signatures des notifications sont vérifiées.
  • Les notifications en double sont traitées sans risque.
  • La recherche via l’API peut servir au rapprochement.

Si vous utilisez la page de paiement Hosted Checkout, vérifiez aussi :

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

Points importants​

  • Dans les intégrations API seule, les clients n’ont pas besoin de passer par Hosted Checkout.
  • La recherche de commande actuelle exige sciName.
  • Une configuration Hosted Checkout peut servir uniquement pour sciName et les notifications à la Status URL, sans afficher la page Hosted Checkout.
  • 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 paymentStatus n’est pas COMPLETED.
  • Utilisez expirationDateMillis pour calculer l’expiration de la facture.
  • 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.
  • Ne créez pas automatiquement une autre facture après un délai d’attente dépassé au résultat incertain ou une erreur temporaire de l’API.