Intégration API

Envoyez des paiements depuis votre compte Volet.com vers des utilisateurs Volet.com et des portefeuilles crypto externes via la Merchant API.

La Mass Payout API permet à votre application de créer, valider et suivre des transactions de paiement de manière programmatique.

Vous pouvez utiliser l’API pour trois scénarios principaux :

Paiements aux utilisateurs Volet.com : envoyez des fonds depuis votre compte Volet.com vers un autre compte Volet.com.
Paiements crypto sans conversion : envoyez des cryptomonnaies depuis le même solde crypto vers un portefeuille crypto externe.
Paiements crypto avec conversion : envoyez des cryptomonnaies vers un portefeuille crypto externe depuis un autre solde pris en charge, comme USD, EUR, USDT ou une autre cryptomonnaie.

Fonctionnement des paiements de masse via l’API

La Merchant API crée une transaction de paiement par requête.

Pour les lots de paiements de masse, votre backend prépare une liste de destinataires et crée une transaction de paiement distincte pour chaque élément du lot.

Un parcours par lots type :

Préparez un lot de paiements dans votre système.
Vérifiez les soldes disponibles de vos portefeuilles Volet.com.
Vérifiez les limites, les tarifs et les taux de change si nécessaire.
Validez chaque paiement avant sa création.
Créez les transactions de paiement via l’API.
Enregistrez dans votre système les identifiants de transaction renvoyés.
Suivez le statut des paiements via l’API.
Rapprochez les paiements effectués, échoués, annulés ou remboursés.

Avant de commencer

Pour envoyer des paiements de masse via l’API, vous avez besoin :

D’un compte Volet.com vérifié.
D’une API configurée dans la section Outils de paiement.
D’un solde suffisant sur votre compte Volet.com.
Des informations sur les destinataires exigées par chaque moyen de paiement.

Consultez Activer les paiements de masse 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 de paiement recommandé

Avant de créer des paiements, votre backend doit valider et préparer chaque élément.

Parcours recommandé :

Récupérez les soldes des portefeuilles.
Vérifiez les limites minimales du moyen de paiement et de la devise choisis.
Vérifiez les tarifs ou les frais.
Vérifiez le taux de change si le paiement utilise une conversion.
Validez la demande de paiement.
Créez la transaction de paiement.
Enregistrez le transactionId renvoyé.
Interrogez le statut de la transaction jusqu’à ce que le paiement atteigne un état final.

Étape 1 : récupérer les soldes des portefeuilles

Utilisez cette méthode pour vérifier les soldes disponibles de vos portefeuilles Volet.com avant de créer des paiements.

Point de terminaison :

GET /api/account/balances

Exemple de réponse :

[
  {
    "walletId": "W000000000001",
    "amount": 1000.50,
    "currency": "USD"
  },
  {
    "walletId": "W000000000002",
    "amount": 2500,
    "currency": "USDT"
  }
]

Utilisez walletId comme portefeuille source lors de la création des demandes de paiement.

Étape 2 : vérifier les limites et les tarifs

Avant d’envoyer des paiements, vérifiez les limites minimales et les tarifs du moyen de paiement et de la paire de devises choisis.

Limites minimales :

GET /api/account/limits/min

Tarifs :

GET /api/account/tariffs

Ces méthodes évitent les erreurs de création de paiement dues à des montants, devises ou moyens de paiement non pris en charge.

Étape 3 : vérifier le taux de change

Consultez le taux de change lorsque le paiement nécessite une conversion.

Point de terminaison :

POST /api/exchange-rate/information

Utilisez-le avant de créer des paiements dont la devise source et la devise de paiement sont différentes.

Exemples d’usage :

Envoyer des USDT vers un portefeuille crypto externe depuis un solde en USD.
Envoyer des BTC vers un portefeuille crypto externe depuis un solde en EUR.
Convertir un solde crypto pris en charge dans une autre devise de paiement.

Moyen 1 : envoyer des paiements aux utilisateurs Volet.com

Utilisez ce moyen lorsque le destinataire a un compte Volet.com.

Les fonds sont transférés en interne de votre compte Volet.com vers le compte Volet.com du destinataire.

Ce moyen ne nécessite pas de confirmation blockchain et n’utilise pas d’adresses de portefeuilles crypto externes.

Valider un paiement à un utilisateur Volet.com

Validez le paiement avant de créer la transaction.

Point de terminaison :

POST /api/withdrawal/validation/internal-other

Exemple de requête :

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

La validation vérifie les informations du paiement sans créer de transaction.

Créer un paiement à un utilisateur Volet.com

Une fois la validation réussie, créez la transaction de paiement.

Point de terminaison :

POST /api/withdrawal/internal-other

Exemple de requête :

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Exemple de réponse :

{
  "transactionId": "11111111-1111-4111-8111-111111111111",
  "paymentMethodType": "INTERNAL_OTHER",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 25,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.13,
  "comment": "Payout batch 2026-06-26 / recipient 001"
}

Enregistrez le transactionId renvoyé dans votre système et utilisez-le pour suivre le statut du paiement.

Facultatif : valider les comptes Volet.com des destinataires

Si votre parcours collecte les adresses e-mail des destinataires avant la création des paiements, vous pouvez vérifier l’existence des comptes Volet.com avant de créer les demandes.

Point de terminaison :

GET /api/account/exists

Vous pouvez aussi vérifier les informations du titulaire du compte si votre parcours exige des contrôles supplémentaires.

Point de terminaison :

GET /api/account/matching

Ces méthodes réduisent les paiements échoués dus à des informations de destinataire erronées.

Moyen 2 : envoyer des paiements crypto sans conversion

Utilisez ce moyen pour envoyer des cryptomonnaies depuis le même solde crypto vers un portefeuille crypto externe.

Par exemple :

Envoyer des USDT depuis votre solde USDT vers une adresse USDT TRC-20 externe.
Envoyer des BTC depuis votre solde BTC vers une adresse BTC externe.
Envoyer des ETH depuis votre solde ETH vers une adresse ETH externe.

Le destinataire n’a pas besoin de compte Volet.com.

Valider un paiement crypto sans conversion

Validez le paiement crypto avant de créer la transaction.

Point de terminaison :

POST /api/withdrawal/validation/cryptowallet

Exemple de requête :

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Utilisez le destCurrency correspondant au token et au réseau blockchain du paiement.

Pour les réseaux qui exigent un memo, un tag de destination ou un identifiant similaire, indiquez-le dans le champ address.memo.

Exemple :

{
  "address": {
    "address": "rXXXXXXXXXXXXXXXXXXXXXXXX",
    "memo": "123456"
  }
}

Créer un paiement crypto sans conversion

Une fois la validation réussie, créez la transaction de paiement.

Point de terminaison :

POST /api/withdrawal/cryptowallet

Exemple de requête :

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Exemple de réponse :

{
  "transactionId": "22222222-2222-4222-8222-222222222222",
  "paymentMethodType": "CRYPTO_WALLET",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000002",
  "fullCommission": 0.25,
  "comment": "Payout batch 2026-06-26 / recipient 002"
}

Moyen 3 : envoyer des paiements crypto avec conversion

Utilisez ce moyen lorsque le solde source et la devise de paiement sont différents.

Par exemple :

Envoyer des USDT vers un portefeuille externe depuis un solde en USD.
Envoyer des BTC vers un portefeuille externe depuis un solde en EUR.
Envoyer des USDC sur un réseau pris en charge depuis un autre solde pris en charge.

Le destinataire reçoit des cryptomonnaies sur un portefeuille crypto externe. La conversion est effectuée pendant le parcours de paiement.

Valider un paiement crypto avec conversion

Validez le paiement avant de créer la transaction.

Point de terminaison :

POST /api/withdrawal/validation/crypto-external

Exemple de requête :

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Utilisez srcCurrency pour définir la devise du solde source et destCurrency pour définir la cryptomonnaie et le réseau envoyés au destinataire.

Créer un paiement crypto avec conversion

Une fois la validation réussie, créez la transaction de paiement.

Point de terminaison :

POST /api/withdrawal/crypto-external

Exemple de requête :

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Exemple de réponse :

{
  "transactionId": "33333333-3333-4333-8333-333333333333",
  "paymentMethodType": "CRYPTO_EXTERNAL",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.50,
  "comment": "Payout batch 2026-06-26 / recipient 003"
}

Champs de la requête

Champs courants des demandes de paiement :

Champ	Obligatoire	Utilisé pour	Description
`srcWalletId`	Non	Tous les moyens de paiement	Identifiant du portefeuille source dans votre compte Volet.com.
`amount`	Oui	Tous les moyens de paiement	Montant du paiement. Son interprétation dépend de `action`.
`action`	Oui	Tous les moyens de paiement	Mode du montant. Valeurs possibles : `GIVE`, `GET`.
`note`	Non	Tous les moyens de paiement	Note interne ou description du paiement.
`srcCurrency`	Non	Paiements aux utilisateurs Volet.com, paiements crypto avec conversion	Devise source du paiement.
`destCurrency`	Oui	Tous les moyens de paiement	Devise créditée au destinataire ou envoyée vers le portefeuille crypto externe.
`destEmail`	Non	Paiements aux utilisateurs Volet.com	Adresse e-mail du compte Volet.com du destinataire.
`destWalletId`	Non	Paiements aux utilisateurs Volet.com	Identifiant du portefeuille du destinataire, le cas échéant.
`address.address`	Oui	Paiements crypto externes	Adresse du portefeuille crypto du destinataire.
`address.memo`	Non	Paiements crypto externes	Memo, tag de destination ou identifiant similaire, si le réseau choisi l’exige.
`receiverInfo`	Non	Paiements crypto externes	Informations sur le destinataire, comme le nom, l’e-mail, la date de naissance ou la raison sociale, si nécessaire.

`GIVE` et `GET`

Utilisez action pour définir l’interprétation du montant du paiement.

Action	Signification
`GIVE`	Le montant correspond au montant à envoyer côté source.
`GET`	Le montant correspond au montant que le destinataire doit recevoir, lorsque c’est pris en charge.

Pour les paiements avec conversion de devise, vérifiez le taux de change avant de créer le paiement. Votre système peut ainsi afficher ou enregistrer les montants source et destination attendus avant la création de la transaction.

Suivi du statut des paiements

Après avoir créé un paiement, enregistrez le transactionId renvoyé.

Utilisez la recherche de transaction pour obtenir le dernier statut du paiement.

Point de terminaison :

GET /api/transactions/{id}

Vous pouvez aussi rechercher dans l’historique des transactions.

Point de terminaison :

GET /api/transactions

Filtres utiles :

Filtre	Description
`paymentDirections`	Filtrer par `DEPOSIT` ou `WITHDRAWAL`.
`transactionStatus`	Filtrer par statut de transaction.
`wallets`	Filtrer par identifiants de portefeuille.
`startDate` / `endDate`	Filtrer par période de création.
`searchLabel`	Rechercher par libellé texte, le cas échéant.
`offset` / `limit`	Paginer les résultats.
`sortOrder`	Trier les résultats par date de création.

Statuts des transactions

Utilisez le statut de la transaction pour mettre à jour le statut du paiement dans votre propre système.

Statut	Signification	Action recommandée
`CREATED`	La transaction de paiement a été créée.	Enregistrez la transaction et poursuivez le suivi.
`READY_TO_PROCESS`	Le paiement est prêt à être traité.	Poursuivez le suivi.
`PENDING`	Le paiement est en attente.	Poursuivez le suivi.
`PROCESSING`	Le paiement est en cours de traitement.	Poursuivez le suivi.
`EXCHANGING`	La conversion de devise est en cours.	Poursuivez le suivi.
`COMPLETED`	Le paiement a été effectué.	Marquez le paiement comme effectué dans votre système.
`CANCELLING`	L’annulation est en cours.	Attendez le statut final.
`CANCELED`	Le paiement a été annulé.	Marquez le paiement comme annulé.
`REFUNDING`	Le remboursement est en cours.	Attendez le statut final.
`REFUNDED`	Le paiement a été remboursé.	Marquez le paiement comme remboursé.

Ne considérez le paiement comme effectué qu’une fois le statut passé à COMPLETED.

Annuler des paiements

Certaines transactions peuvent être annulées tant que l’annulation reste possible.

Point de terminaison :

DELETE /api/transactions/{transactionId}

La possibilité d’annuler dépend du moyen de paiement, du statut de la transaction et de l’étape de traitement.

Ne comptez pas sur l’annulation des paiements crypto une fois la transaction diffusée sur la blockchain. Vérifiez toutes les adresses, devises, réseaux et montants des destinataires avant de créer le paiement.

Recommandations pour le traitement par lots

Pour les paiements de masse, votre backend doit gérer le cycle de vie du lot.

Approche recommandée :

Attribuez un identifiant interne au lot de paiements.
Attribuez un identifiant interne à chaque paiement.
Validez chaque élément avant de créer les transactions.
Ne créez des transactions que pour les éléments validés.
Enregistrez la correspondance entre votre identifiant interne d’élément et le transactionId renvoyé.
Suivez chaque transaction séparément.
Ne relancez que les éléments échoués ou non créés.
Rapprochez les statuts finaux avant de marquer le lot comme terminé.

Évitez d’envoyer des paiements en double. Si votre application relance une requête après un délai d’attente dépassé, vérifiez d’abord si une transaction a déjà été créée pour cet élément.

Gestion des erreurs

Les erreurs de la Merchant API renvoient des réponses d’erreur structurées.

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 paiement de remplacement avant d’avoir confirmé qu’aucune transaction n’a été créée.
Ne réessayez que lorsque c’est sans risque.

Liste de contrôle des tests

Avant d’envoyer des paiements de masse réels, testez le parcours complet.

Pour les paiements aux utilisateurs Volet.com :

Validation du compte du destinataire.
Validation du paiement.
Création du paiement.
Suivi du statut de la transaction.
Scénarios effectués, annulés et échoués.

Pour les paiements crypto sans conversion :

Choix correct du token et du réseau.
Gestion de l’adresse et du memo.
Validation du paiement.
Création du paiement.
Suivi de la transaction blockchain.
Gestion d’une adresse erronée ou d’un réseau non pris en charge.

Pour les paiements crypto avec conversion :

Vérification du solde.
Vérification du taux de change.
Validation du paiement.
Création du paiement.
Statuts EXCHANGING et COMPLETED.
Rapprochement des montants entre devise source et devise de destination.

Pour le traitement par lots :

Gestion des échecs partiels d’un lot.
Logique de relance.
Prévention des doublons.
Correspondance interne entre lots et transactions.
Rapport de rapprochement final.

Points importants

L’API crée une transaction de paiement par requête.
L’orchestration des lots incombe à votre backend.
Validez toujours les paiements avant de créer les transactions.
Enregistrez toujours les valeurs de transactionId renvoyées.
Utilisez la recherche de transaction ou l’historique pour suivre le statut final.
Ne marquez pas un paiement comme effectué tant que son statut n’est pas COMPLETED.
Pour les paiements crypto, vérifiez toujours l’adresse, le token, le réseau et le memo du destinataire avant de créer la transaction.
Envoyer de la crypto à une mauvaise adresse ou sur un mauvais réseau peut entraîner la perte définitive des fonds.
Les identifiants de l’API ne doivent jamais être exposés dans le code frontend.

Activer les paiements de masse — configurez votre API avant d’envoyer des paiements
Envoyer des paiements aux utilisateurs Volet.com — envoyez des paiements internes vers des comptes Volet.com
Envoyer des paiements crypto dépositaires — envoyez de la crypto vers des portefeuilles externes depuis votre compte Volet.com
Présentation des paiements de masse — comparez les moyens et les modèles de paiement
Référence de l’API — documentation complète des méthodes, paramètres et réponses

Fonctionnement des paiements de masse via l’API​

Avant de commencer​

Authentification​

Parcours de paiement recommandé​

Étape 1 : récupérer les soldes des portefeuilles​

Étape 2 : vérifier les limites et les tarifs​

Étape 3 : vérifier le taux de change​

Moyen 1 : envoyer des paiements aux utilisateurs Volet.com​

Valider un paiement à un utilisateur Volet.com​

Créer un paiement à un utilisateur Volet.com​

Facultatif : valider les comptes Volet.com des destinataires​

Moyen 2 : envoyer des paiements crypto sans conversion​

Valider un paiement crypto sans conversion​

Créer un paiement crypto sans conversion​

Moyen 3 : envoyer des paiements crypto avec conversion​

Valider un paiement crypto avec conversion​

Créer un paiement crypto avec conversion​

Champs de la requête​

GIVE et GET​

Suivi du statut des paiements​

Statuts des transactions​

Annuler des paiements​

Recommandations pour le traitement par lots​

Gestion des erreurs​

Liste de contrôle des tests​

Points importants​

Voir aussi​

Fonctionnement des paiements de masse via l’API

Avant de commencer

Authentification

Parcours de paiement recommandé

Étape 1 : récupérer les soldes des portefeuilles

Étape 2 : vérifier les limites et les tarifs

Étape 3 : vérifier le taux de change

Moyen 1 : envoyer des paiements aux utilisateurs Volet.com

Valider un paiement à un utilisateur Volet.com

Créer un paiement à un utilisateur Volet.com

Facultatif : valider les comptes Volet.com des destinataires

Moyen 2 : envoyer des paiements crypto sans conversion

Valider un paiement crypto sans conversion

Créer un paiement crypto sans conversion

Moyen 3 : envoyer des paiements crypto avec conversion

Valider un paiement crypto avec conversion

Créer un paiement crypto avec conversion

Champs de la requête

`GIVE` et `GET`

Suivi du statut des paiements

Statuts des transactions

Annuler des paiements

Recommandations pour le traitement par lots

Gestion des erreurs

Liste de contrôle des tests

Points importants

Voir aussi