Passer au contenu principal
L’API des Comptes Virtuels fournit des endpoints pour gerer les comptes bancaires virtuels lies aux portefeuilles principaux ou aux adresses enfants. Cette API permet aux entreprises de creer des comptes virtuels pour que les clients recoivent des paiements, de recuperer les details des comptes virtuels et d’activer/desactiver les comptes virtuels.

​
Introduction

Les Comptes Virtuels permettent a vos clients de recevoir des paiements fiat via des virements bancaires traditionnels, qui sont automatiquement convertis en stablecoins sur la blockchain. Cela fait le pont entre la banque traditionnelle et les paiements en stablecoins, permettant un traitement des paiements fluide pour votre entreprise. Lorsqu’un client envoie de la monnaie fiat a un compte virtuel, le systeme peut automatiquement emettre l’equivalent en stablecoin et le transferer vers le portefeuille ou l’adresse liee, fournissant des capacites de traitement des paiements en temps reel.

​
Comment Fonctionnent les Comptes Virtuels

Creation de Compte

Creez des comptes virtuels lies a des portefeuilles principaux ou des adresses enfants avec les informations du client.

Reception de Paiement

Les clients envoient des paiements fiat au compte virtuel en utilisant des virements bancaires traditionnels.

Financement Automatique

Pour les comptes de type AUTO_FUNDING, les paiements declenchent automatiquement l’emission du stablecoin.

Gestion des Fonds

Les stablecoins emis sont transferes vers le portefeuille ou l’adresse liee pour une utilisation immediate.

​
Types de Comptes Virtuels

Les comptes virtuels prennent en charge differents types avec des comportements varies :

​
AUTO_FUNDING (Par defaut)

  • Emet automatiquement le stablecoin lorsque les paiements fiat sont recus
  • Transfere le stablecoin vers le portefeuille/l’adresse liee immediatement
  • Ideal pour le traitement des paiements en temps reel
  • Fournit une conversion instantanee du fiat au stablecoin
Le flux de financement automatique ne s’applique qu’aux comptes virtuels de type AUTO_FUNDING. Les autres types ont des comportements de traitement differents.

​
Comment Ca Marche - Flux de Financement Automatique

Lorsqu’un client envoie de la monnaie fiat a un compte virtuel de type AUTO_FUNDING :

​
1. Reception du Paiement

Le paiement est recu dans le compte virtuel via un virement bancaire traditionnel. Un webhook deposit.processing est declenche a cette etape.

​
2. Emission Automatique

Le systeme emet automatiquement l’equivalent en stablecoin sur la blockchain.

​
3. Transfert Blockchain

Le stablecoin emis est transfere vers le portefeuille ou l’adresse liee au compte virtuel. Un webhook deposit.success est declenche lors de la completion reussie.
Le flux de financement automatique ne s’applique qu’aux comptes virtuels de type AUTO_FUNDING. Les autres types ont des comportements de traitement differents.

​
Prerequis

Avant de creer des comptes virtuels, assurez-vous :
  • Les exigences de conformite doivent etre completees (voir la section Exigences de Conformite ci-dessous)
  • La fonctionnalite des comptes virtuels doit etre activee pour votre entreprise (contactez [email protected] ou utilisez le chat en direct sur le tableau de bord pour activer la fonctionnalite apres l’approbation de conformite)
  • Disponible uniquement sur l’environnement MAINNET (non disponible sur testnet)
  • Le Portefeuille Principal doit prendre en charge l’actif stablecoin - Votre plan de compte doit inclure l’acces aux stablecoins (mise a niveau depuis Tableau de bord -> Parametres -> Abonnement si necessaire)
Environnement : Les comptes virtuels sont uniquement disponibles dans l’environnement MAINNET. Les environnements Testnet ne prennent pas en charge la creation ou les operations des comptes virtuels.

​
Exigences de Conformite

Avant de demander l’acces a la fonctionnalite des comptes virtuels, vous devez completer le processus d’integration de conformite. Les documents et informations suivants sont requis :

​
Documents Requis

  1. Certificat de Constitution pour votre entreprise et une liste des actionnaires (ex. document MEMART du CAC nigerien)
  2. Facture de services publics recente pour confirmer l’adresse de l’entreprise
  3. Cartes d’identite des UBO(s) (Beneficiaires Effectifs Ultimes) et des Directeurs
  4. Certificat Fiscal/NIF
  5. Politique KYC de l’Entreprise
  6. Politique AML/CFT/CPF de l’Entreprise
  7. Factures de services publics recentes des UBO(s) et des Directeurs

​
Soumission des Documents de Conformite

Soumettez tous les documents et informations requis par email a l’equipe de conformite :
Le processus d’examen de conformite doit etre complete avant que les comptes virtuels puissent etre actives pour votre entreprise. Veuillez vous assurer que tous les documents sont a jour et correctement formates avant la soumission.

​
Devise Prise en Charge

  • Fiat : NGN (Naira nigerien) - Virements bancaires traditionnels
  • Stablecoin : cNGN - Emis automatiquement sur la blockchain (pour le type AUTO_FUNDING)

​
Endpoints API

Voici les endpoints API principaux pour les operations des Comptes Virtuels :

​
Endpoints du Portefeuille Principal

​
Endpoints de l’Adresse Enfant

​
Creation des Comptes Virtuels

Vous pouvez creer des comptes virtuels pour les portefeuilles principaux et les adresses enfants, selon votre cas d’utilisation. Utilisez l’API de Creation de Compte Virtuel pour les portefeuilles principaux ou l’API de Creation de Compte Virtuel pour les adresses enfants.

​
Parametres de Requete

ParametreTypeRequisDescription
firstnamestringOuiPrenom du client
lastnamestringOuiNom de famille du client
emailstringOuiAdresse email du client (doit etre unique par entreprise)
phonestringOuiNumero de telephone du client au format : +234XXXXXXXXXX

​
Exemple de Reponse

{
  "data": {
    "id": "8180309e-1ead-4a72-a013-b5674600ce4c",
    "accountName": "John Doe",
    "accountNumber": "9018927611",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "type": "AUTO_FUNDING",
    "isActive": true,
    "status": "ACTIVE",
    "reference": "20",
    "customer": {
      "id": "caa17eb8-4da8-45b4-a866-81dd0a1df613",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+2348161846125",
      "status": "ACTIVE",
      "network": "mainnet"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet",
      "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
    },
    "createdAt": "2025-11-06T18:30:34.286Z",
    "updatedAt": "2025-11-06T18:30:34.286Z"
  },
  "message": "Virtual account created successfully",
  "statusCode": 201
}

​
Recuperation des Comptes Virtuels

Pour recuperer les details du compte virtuel, utilisez l’API de Recuperation de Compte Virtuel pour les portefeuilles principaux ou l’API de Recuperation de Compte Virtuel pour les adresses enfants.

​
Mise a Jour des Comptes Virtuels

Vous pouvez activer ou desactiver les comptes virtuels pour controler le comportement du financement automatique. Utilisez l’API de Mise a Jour de Compte Virtuel pour les portefeuilles principaux ou l’API de Mise a Jour de Compte Virtuel pour les adresses enfants.

​
Comportement du Financement Automatique

  • Comptes actifs : Les paiements recus declenchent l’emission automatique de stablecoins
  • Comptes inactifs : Les paiements sont recus mais le financement automatique est desactive

​
Parametres de Mise a Jour

ParametreTypeRequisDescription
isActivebooleanOuitrue pour activer, false pour desactiver
Lorsqu’un compte virtuel est desactive (isActive: false), les paiements peuvent toujours etre recus mais le processus d’emission et de transfert automatique de stablecoins est desactive. Vous pouvez reactiver le compte a tout moment pour reactiver le financement automatique.

​
Webhooks

Les comptes virtuels declenchent des evenements webhook lorsque les paiements sont recus et traites. Pour les comptes de type AUTO_FUNDING, vous recevrez des notifications webhook a chaque etape du flux de traitement des paiements.

​
Evenements Webhook

Lorsqu’un client envoie un paiement fiat a un compte virtuel de type AUTO_FUNDING :
  1. deposit.processing - Declenche immediatement lorsque le paiement fiat est recu dans le compte virtuel. Cela indique que le paiement a ete detecte et que le processus d’emission est sur le point de commencer.
  2. deposit.success - Declenche lorsque le stablecoin a ete emis et transfere avec succes vers le portefeuille ou l’adresse liee. Cela confirme que l’ensemble du processus de financement automatique est termine.
  3. deposit.failed - Declenche si le processus d’emission ou de transfert echoue a un moment donne.
  4. deposit.cancelled - Declenche si la transaction est annulee avant son achevement.

​
Payload Webhook

Le payload webhook suit le format de webhook de depot standard. Le type de transaction sera DEPOSIT, et le champ status refletera l’etat actuel (PROCESSING, SUCCESS, FAILED, ou CANCELLED).
Les webhooks ne sont declenches que pour les comptes virtuels actifs (isActive: true). Si un compte est desactive, les paiements peuvent toujours etre recus mais les evenements webhook ne seront pas envoyes jusqu’a ce que le compte soit reactive.
Pour plus d’informations sur la configuration des webhooks, la structure du payload et la gestion des evenements, consultez la documentation des Webhooks.

​
Cas d’Utilisation

​
Paiements E-commerce

Creez des comptes virtuels pour que les clients recoivent des paiements pour des produits ou services. La conversion automatique en stablecoins permet une integration fluide avec votre systeme de paiement base sur la blockchain.

​
Services d’Abonnement

Liez des comptes virtuels aux abonnements clients, permettant des paiements recurrents via des virements bancaires traditionnels qui sont automatiquement convertis en stablecoins.

​
Transactions de Marketplace

Activez des transactions pair-a-pair ou les clients peuvent envoyer des paiements fiat qui sont instantanement convertis en stablecoins et credites sur leur portefeuille.

​
Services de Transfert d’Argent

Fournissez aux clients des comptes virtuels pour recevoir des transferts en NGN, qui sont automatiquement convertis en stablecoins pour des transferts transfrontaliers faciles.

​
Bonnes Pratiques

​
Gestion des Comptes

  • Adresses email uniques : Assurez-vous que chaque client a une adresse email unique
  • Format du numero de telephone : Utilisez toujours le format correct (+234XXXXXXXXXX) pour les numeros de telephone nigeriens
  • Activation du compte : N’activez les comptes que lorsque vous etes pret a traiter les paiements
  • Surveiller le statut du compte : Verifiez regulierement le statut du compte et gerez les comptes inactifs de maniere appropriee

​
Securite

  • Verification du client : Verifiez les informations du client avant de creer des comptes virtuels
  • Validation du compte : Validez les details du compte avant de traiter les paiements
  • Controle d’acces : Implementez des controles d’acces appropries pour la gestion des comptes virtuels

​
Support et Ressources

​
Obtenir de l’Aide

Les comptes virtuels fournissent un moyen puissant de faire le pont entre la banque traditionnelle et les paiements blockchain. Commencez par creer des comptes pour vos portefeuilles principaux, puis etendez aux adresses enfants selon vos besoins. Assurez-vous toujours que vos portefeuilles prennent en charge le stablecoin pour les comptes de type AUTO_FUNDING.


Bon codage !