Comptes Virtuels - Blockradar

En résumé
Les Comptes Virtuels permettent à vos clients de recevoir des paiements fiat via des virements bancaires traditionnels, qui sont automatiquement convertis en stablecoins sur la blockchain. Vous pouvez créer plusieurs comptes virtuels par portefeuille ou adresse, avec support pour l’étiquetage, la pagination et la régénération de comptes.

Prérequis

Avant d’utiliser l’API des Comptes Virtuels, assurez-vous d’avoir :

Clé API

Obtenez votre clé API depuis le Tableau de bord Blockradar. Naviguez vers Developers pour en générer une.

Portefeuille Créé

Créez un portefeuille via l’API Créer Portefeuille ou le tableau de bord. Vous aurez besoin du walletId pour les opérations de comptes virtuels.

Conformité Approuvée

Complétez le processus d’intégration de conformité (voir Exigences de Conformité ci-dessous). Soumettez les documents requis à [email protected].

Fonctionnalité Activée

Demandez l’activation de la fonctionnalité des comptes virtuels après l’approbation de conformité. Contactez [email protected] ou utilisez le chat en direct sur le tableau de bord.

Environnement Mainnet

Les comptes virtuels ne sont disponibles que sur MAINNET. Les environnements testnet ne prennent pas en charge les opérations de comptes virtuels.

Support Stablecoin

Assurez-vous que votre plan de compte inclut l’accès aux stablecoins. Mettez à niveau depuis Tableau de bord → Paramètres → Abonnement si nécessaire.

Comment Ça Fonctionne

Création de Compte

Créez des comptes virtuels liés à des portefeuilles principaux ou des adresses enfants avec les informations du client.

Réception de Paiement

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

Financement Automatique

Les paiements déclenchent automatiquement l’émission de l’équivalent en stablecoin.

Gestion des Fonds

Les stablecoins émis sont transférés vers le portefeuille ou l’adresse liée pour une utilisation immédiate.

Types de Comptes Virtuels

AUTO_FUNDING

Tous les comptes virtuels sont créés avec le type AUTO_FUNDING, qui fournit une conversion automatique fiat-vers-stablecoin :

Émet automatiquement le stablecoin lorsque les paiements fiat sont reçus
Transfère le stablecoin vers le portefeuille/l’adresse liée immédiatement
Idéal pour le traitement des paiements en temps réel
Fournit une conversion instantanée du fiat au stablecoin

Flux de Financement Automatique

Lorsqu’un client envoie de la monnaie fiat à un compte virtuel :

1. Réception du Paiement

Le paiement est reçu dans le compte virtuel via un virement bancaire traditionnel. Un webhook deposit.processing est déclenché à cette étape.

2. Émission Automatique

Le système émet automatiquement l’équivalent en stablecoin sur la blockchain.

3. Transfert Blockchain

Le stablecoin émis est transféré vers le portefeuille ou l’adresse liée au compte virtuel. Un webhook deposit.success est déclenché lors de la complétion réussie.

Exigences de Conformité

Avant de demander l’accès à la fonctionnalité des comptes virtuels, vous devez compléter le processus d’intégration de conformité. Les documents et informations suivants sont requis :

Documents Requis

Certificat de Constitution pour votre entreprise et une liste des actionnaires (ex. document MEMART du CAC nigérien)
Facture de services publics récente pour confirmer l’adresse de l’entreprise
Cartes d’identité des UBO(s) (Bénéficiaires Effectifs Ultimes) et des Directeurs
Certificat Fiscal/NIF
Politique KYC de l’Entreprise
Politique AML/CFT/CPF de l’Entreprise
Factures de services publics récentes des UBO(s) et des Directeurs

Soumission des Documents de Conformité

Soumettez tous les documents et informations requis par email à l’équipe de conformité :

Email : [email protected]
CC : [email protected], [email protected]

Le processus d’examen de conformité doit être complété avant que les comptes virtuels puissent être activés pour votre entreprise. Veuillez vous assurer que tous les documents sont à jour et correctement formatés avant la soumission.

Devise Prise en Charge

Fiat : NGN (Naira nigérien) - Virements bancaires traditionnels
Stablecoin : cNGN - Émis automatiquement sur la blockchain

Endpoints API

Voici les endpoints API principaux pour les opérations des Comptes Virtuels :

Endpoints du Portefeuille Principal

POST /wallets//virtual-accounts – Créer un compte virtuel pour un portefeuille principal
GET /wallets//virtual-accounts – Lister tous les comptes virtuels (paginé)
GET /wallets//virtual-accounts/ – Récupérer un compte virtuel spécifique
GET /wallets//virtual-accounts//transactions – Obtenir les transactions d’un compte virtuel
PATCH /wallets//virtual-accounts/ – Mettre à jour le statut du compte virtuel
POST /wallets//virtual-accounts//regenerate – Régénérer un compte virtuel

Endpoints de l’Adresse Enfant

POST /wallets//addresses//virtual-accounts – Créer un compte virtuel pour une adresse enfant
GET /wallets//addresses//virtual-accounts – Lister tous les comptes virtuels (paginé)
GET /wallets//addresses//virtual-accounts/ – Récupérer un compte virtuel spécifique
GET /wallets//addresses//virtual-accounts//transactions – Obtenir les transactions d’un compte virtuel
PATCH /wallets//addresses//virtual-accounts/ – Mettre à jour le statut du compte virtuel
POST /wallets//addresses//virtual-accounts//regenerate – Régénérer un compte virtuel

Création des Comptes Virtuels

Vous pouvez créer des comptes virtuels pour les portefeuilles principaux et les adresses enfants, selon votre cas d’utilisation. Utilisez l’API de Création de Compte Virtuel pour les portefeuilles principaux ou l’API de Création de Compte Virtuel pour les adresses enfants.

Paramètres de Requête

Paramètre	Type	Requis	Description
`firstname`	string	Oui	Prénom du client (max 29 caractères)
`lastname`	string	Oui	Nom de famille du client (max 29 caractères)
`email`	string	Oui	Adresse email du client (doit être unique par entreprise)
`phone`	string	Non	Numéro de téléphone du client au format : +234XXXXXXXXXX
`label`	string	Non	Étiquette personnalisée pour identifier ce compte virtuel (max 100 caractères)

Exemple de Requête

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "label": "Compte Principal"
}

Exemple de Réponse

{
  "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",
    "label": "Compte Principal",
    "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
}

Comptes Virtuels Multiples

Vous pouvez créer plusieurs comptes virtuels par portefeuille ou adresse enfant. Ceci est utile lorsque :

Un client a besoin de comptes séparés pour différents usages (ex. épargne, paiements)
Vous souhaitez suivre les paiements de différentes sources séparément
Le compte virtuel existant d’un client doit être remplacé tout en conservant l’historique

Un seul compte virtuel par email client peut être actif à la fois. La création d’un nouveau compte virtuel pour le même email nécessitera de désactiver d’abord l’existant, ou d’utiliser l’endpoint de régénération.

Liste des Comptes Virtuels

L’endpoint de liste retourne une liste paginée de tous les comptes virtuels. Utilisez les paramètres de requête pour filtrer et paginer les résultats.

Paramètres de Requête

Paramètre	Type	Description
`page`	number	Numéro de page (par défaut : 1)
`limit`	number	Résultats par page (par défaut : 10)
`isActive`	boolean	Filtrer par statut actif (`true` ou `false`)

Exemple de Réponse

{
  "message": "Virtual accounts retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "597ef702-f096-4f8a-a542-29e8757ba208",
      "reference": "172",
      "accountNumber": "9012271961",
      "accountName": "test user",
      "bankName": "Polaris Bank",
      "bankCode": "076",
      "currency": "NGN",
      "isActive": true,
      "status": "ACTIVE",
      "type": "AUTO_FUNDING",
      "label": null,
      "createdAt": "2026-01-21T22:15:55.746Z",
      "updatedAt": "2026-01-21T22:15:55.746Z",
      "customer": {
        "id": "3082e278-557a-44f0-9205-c2639560cd5a",
        "name": "test user",
        "email": "[email protected]",
        "phone": "+2346112768485",
        "status": "ACTIVE",
        "network": "mainnet"
      },
      "wallet": {
        "id": "35e964a6-436a-424f-bf3a-618cc060feea",
        "name": "Base Wallet",
        "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
      },
      "address": null
    }
  ],
  "meta": {
    "totalItems": 4,
    "itemCount": 4,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

Récupération d’un Compte Virtuel

Pour récupérer un compte virtuel spécifique par ID, utilisez l’API de Récupération de Compte Virtuel pour les portefeuilles principaux ou l’API de Récupération de Compte Virtuel pour les adresses enfants.

Exemple de Réponse

{
  "message": "Virtual account retrieved successfully",
  "statusCode": 200,
  "data": {
    "id": "597ef702-f096-4f8a-a542-29e8757ba208",
    "reference": "172",
    "accountNumber": "9012271961",
    "accountName": "John Doe",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "isActive": true,
    "status": "ACTIVE",
    "type": "AUTO_FUNDING",
    "label": "Compte Principal",
    "createdAt": "2026-01-21T22:15:55.746Z",
    "updatedAt": "2026-01-21T22:15:55.746Z",
    "customer": {
      "id": "3082e278-557a-44f0-9205-c2639560cd5a",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+2348161846125",
      "status": "ACTIVE",
      "network": "mainnet"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet",
      "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
    },
    "address": null
  }
}

Transactions de Compte Virtuel

Vous pouvez récupérer toutes les transactions associées à un compte virtuel spécifique en utilisant l’endpoint des transactions.

Paramètres de Requête

Paramètre	Type	Description
`page`	number	Numéro de page (par défaut : 1)
`limit`	number	Résultats par page (par défaut : 10)

Exemple de Réponse

{
  "message": "Virtual account transactions retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
      "reference": "auto-funding-09026725110701402449700167083590131815",
      "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4",
      "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "amount": "50.0",
      "amountPaid": "50.0",
      "amountUSD": "0.03382",
      "currency": "NGN",
      "status": "SUCCESS",
      "type": "DEPOSIT",
      "note": "Auto funding of 50.0 cNGN to 0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "network": "mainnet",
      "metadata": {
        "autoFunding": {
          "narration": "NIBSS:9018927611:SULEIMAN, ABDULFATAI:Sending:090267251107014024497001670835",
          "sessionId": "09026725110701402449700167083590131815",
          "senderBankName": "KUDA MFB",
          "senderAccountName": "SULEIMAN, ABDULFATAI"
        }
      },
      "createdAt": "2026-01-22T22:29:28.679Z",
      "asset": {
        "name": "cNGN",
        "symbol": "cNGN",
        "currency": "NGN"
      },
      "blockchain": {
        "name": "base",
        "slug": "base"
      }
    }
  ],
  "meta": {
    "totalItems": 1,
    "itemCount": 1,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

Le champ metadata.autoFunding contient des détails sur la source du paiement fiat, y compris le nom de la banque de l’expéditeur, le nom du compte et la narration du virement bancaire.

Régénération des Comptes Virtuels

L’endpoint de régénération vous permet de créer un nouveau compte virtuel pour un client tout en désactivant l’existant. Ceci est utile lorsque :

Les coordonnées bancaires d’un client doivent changer
Le compte virtuel a été compromis
Vous devez migrer un client vers une autre banque

Paramètres de Régénération

Paramètre	Type	Requis	Description
`firstname`	string	Oui	Prénom du client (max 29 caractères)
`lastname`	string	Oui	Nom de famille du client (max 29 caractères)
`email`	string	Oui	Adresse email du client
`phone`	string	Non	Numéro de téléphone du client au format : +234XXXXXXXXXX
`reason`	string	Oui	Raison de la régénération du compte virtuel
`label`	string	Non	Étiquette personnalisée pour le nouveau compte virtuel

Exemple de Requête

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "reason": "Le client a demandé un nouveau numéro de compte",
  "label": "Nouveau Compte Principal"
}

L’opération de régénération désactivera le compte virtuel existant et en créera un nouveau. L’historique des transactions du compte original est préservé et peut toujours être consulté.

Mise à Jour des Comptes Virtuels

Vous pouvez activer ou désactiver les comptes virtuels pour contrôler le comportement du financement automatique. Utilisez l’API de Mise à Jour de Compte Virtuel pour les portefeuilles principaux ou l’API de Mise à Jour de Compte Virtuel pour les adresses enfants.

Comportement du Financement Automatique

Comptes actifs : Les paiements reçus déclenchent l’émission automatique de stablecoins
Comptes inactifs : Les paiements sont reçus mais le financement automatique est désactivé

Paramètres de Mise à Jour

Paramètre	Type	Requis	Description
`isActive`	boolean	Oui	`true` pour activer, `false` pour désactiver

Exemple de Requête

{
  "isActive": false
}

Exemple de Réponse

{
  "message": "Virtual account updated successfully",
  "statusCode": 200,
  "data": {
    "id": "597ef702-f096-4f8a-a542-29e8757ba208",
    "accountNumber": "9012271961",
    "accountName": "John Doe",
    "bankName": "Polaris Bank",
    "isActive": false,
    "status": "INACTIVE",
    "type": "AUTO_FUNDING",
    "label": "Compte Principal"
  }
}

Lorsqu’un compte virtuel est désactivé (isActive: false), les paiements peuvent toujours être reçus mais le processus d’émission et de transfert automatique de stablecoins est désactivé. Vous pouvez réactiver le compte à tout moment pour réactiver le financement automatique.

Webhooks

Les comptes virtuels déclenchent des événements webhook lorsque les paiements sont reçus et traités. Vous recevrez des notifications webhook à chaque étape du flux de traitement des paiements.

Événements Webhook

Lorsqu’un client envoie un paiement fiat à un compte virtuel :

deposit.processing - Déclenché immédiatement lorsque le paiement fiat est reçu dans le compte virtuel. Cela indique que le paiement a été détecté et que le processus d’émission est sur le point de commencer.
deposit.success - Déclenché lorsque le stablecoin a été émis et transféré avec succès vers le portefeuille ou l’adresse liée. Cela confirme que l’ensemble du processus de financement automatique est terminé.
deposit.failed - Déclenché si le processus d’émission ou de transfert échoue à un moment donné.
deposit.cancelled - Déclenché si la transaction est annulée avant son achèvement.

Exemple de Payload Webhook

{
  "event": "deposit.success",
  "data": {
    "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
    "reference": "auto-funding-09026725110701402449700167083590131815",
    "amount": "50.0",
    "currency": "NGN",
    "status": "SUCCESS",
    "type": "DEPOSIT",
    "network": "mainnet",
    "metadata": {
      "autoFunding": {
        "sessionId": "09026725110701402449700167083590131815",
        "senderBankName": "KUDA MFB",
        "senderAccountName": "SULEIMAN, ABDULFATAI"
      }
    },
    "virtualAccount": {
      "id": "597ef702-f096-4f8a-a542-29e8757ba208",
      "accountNumber": "9012271961",
      "bankName": "Polaris Bank"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet"
    }
  }
}

Les webhooks ne sont déclenchés que pour les comptes virtuels actifs (isActive: true). Si un compte est désactivé, les paiements peuvent toujours être reçus mais les événements webhook ne seront pas envoyés jusqu’à ce que le compte soit réactivé.

Pour plus d’informations sur la configuration des webhooks, la structure du payload et la gestion des événements, consultez la documentation des Webhooks.

Cas d’Utilisation

Paiements E-commerce

Créez des comptes virtuels pour que les clients reçoivent des paiements pour des produits ou services. La conversion automatique en stablecoins permet une intégration fluide avec votre système de paiement basé sur la blockchain.

Services d’Abonnement

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

Transactions de Marketplace

Activez des transactions pair-à-pair où les clients peuvent envoyer des paiements fiat qui sont instantanément convertis en stablecoins et crédités 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

Utilisez des étiquettes descriptives : Ajoutez des étiquettes significatives aux comptes virtuels (ex. “Épargne”, “Paiements”) pour une identification facile
Adresses email uniques : Assurez-vous que chaque client a une adresse email unique par compte actif
Format du numéro de téléphone : Utilisez toujours le format correct (+234XXXXXXXXXX) pour les numéros de téléphone nigériens
Activation du compte : N’activez les comptes que lorsque vous êtes prêt à traiter les paiements
Surveiller le statut du compte : Vérifiez régulièrement le statut du compte et gérez les comptes inactifs de manière appropriée
Documenter les raisons de régénération : Fournissez toujours des raisons claires lors de la régénération des comptes à des fins d’audit

Comptes Multiples

Planifiez votre structure de comptes : Décidez à l’avance combien de comptes chaque client peut nécessiter
Utilisez les étiquettes de manière cohérente : Établissez une convention de nommage pour les étiquettes dans votre application
Suivez l’historique des comptes : Lors de la régénération, conservez les références aux ID de comptes précédents pour la réconciliation des transactions

Sécurité

Vérification du client : Vérifiez les informations du client avant de créer des comptes virtuels
Validation du compte : Validez les détails du compte avant de traiter les paiements
Contrôle d’accès : Implémentez des contrôles d’accès appropriés pour la gestion des comptes virtuels

Gestion des Erreurs

L’API retourne des codes de statut HTTP standard et des réponses d’erreur. Les erreurs courantes incluent :

Code de Statut	Erreur	Description
`400`	Bad Request	Paramètres de requête invalides (ex. format d’email invalide, nom dépassant 29 caractères)
`401`	Unauthorized	Clé API manquante ou invalide
`404`	Not Found	Compte virtuel ou portefeuille non trouvé
`409`	Conflict	L’email existe déjà pour un compte virtuel actif
`422`	Unprocessable Entity	Validation échouée (ex. champs requis manquants)

Exemple de Réponse d’Erreur

{
  "message": "A virtual account with this email already exists",
  "statusCode": 409,
  "error": "Conflict"
}

Lorsque vous recevez une erreur 409 pour email en double, désactivez d’abord le compte virtuel existant ou utilisez l’endpoint de régénération pour créer un nouveau compte pour le même client.

Support et Ressources

Obtenir de l’Aide

Support pour plus de stablecoins et devises : Contactez [email protected] pour activer le support pour votre stablecoin et devise
Email : [email protected]
Chat en direct : Disponible sur le tableau de bord
Référence API : Comptes Virtuels

Les comptes virtuels fournissent un moyen puissant de faire le pont entre la banque traditionnelle et les paiements blockchain. Commencez par créer des comptes pour vos portefeuilles principaux, puis étendez 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 ! ❤️

Démarrage

Essentiels

​Prérequis

​Comment Ça Fonctionne

Création de Compte

Réception de Paiement

Financement Automatique

Gestion des Fonds

​Types de Comptes Virtuels

​AUTO_FUNDING

​Flux de Financement Automatique

​1. Réception du Paiement

​2. Émission Automatique

​3. Transfert Blockchain

​Exigences de Conformité

​Documents Requis

​Soumission des Documents de Conformité

​Devise Prise en Charge

​Endpoints API

​Endpoints du Portefeuille Principal

​Endpoints de l’Adresse Enfant

​Création des Comptes Virtuels

​Paramètres de Requête

​Exemple de Requête

​Exemple de Réponse

​Comptes Virtuels Multiples

​Liste des Comptes Virtuels

​Paramètres de Requête

​Exemple de Réponse

​Récupération d’un Compte Virtuel

​Exemple de Réponse

​Transactions de Compte Virtuel

​Paramètres de Requête

​Exemple de Réponse

​Régénération des Comptes Virtuels

​Paramètres de Régénération

​Exemple de Requête

​Mise à Jour des Comptes Virtuels

​Comportement du Financement Automatique

​Paramètres de Mise à Jour

​Exemple de Requête

​Exemple de Réponse

​Webhooks

​Événements Webhook

​Exemple de Payload Webhook

​Cas d’Utilisation

​Paiements E-commerce

​Services d’Abonnement

​Transactions de Marketplace

​Services de Transfert d’Argent

​Bonnes Pratiques

​Gestion des Comptes

​Comptes Multiples

​Sécurité

​Gestion des Erreurs

​Exemple de Réponse d’Erreur

​Support et Ressources

​Obtenir de l’Aide

Prérequis

Comment Ça Fonctionne

Types de Comptes Virtuels

AUTO_FUNDING

Flux de Financement Automatique

1. Réception du Paiement

2. Émission Automatique

3. Transfert Blockchain

Exigences de Conformité

Documents Requis

Soumission des Documents de Conformité

Devise Prise en Charge

Endpoints API

Endpoints du Portefeuille Principal

Endpoints de l’Adresse Enfant

Création des Comptes Virtuels

Paramètres de Requête

Exemple de Requête

Exemple de Réponse

Comptes Virtuels Multiples

Liste des Comptes Virtuels

Paramètres de Requête

Exemple de Réponse

Récupération d’un Compte Virtuel

Exemple de Réponse

Transactions de Compte Virtuel

Paramètres de Requête

Exemple de Réponse

Régénération des Comptes Virtuels

Paramètres de Régénération

Exemple de Requête

Mise à Jour des Comptes Virtuels

Comportement du Financement Automatique

Paramètres de Mise à Jour

Exemple de Requête

Exemple de Réponse

Webhooks

Événements Webhook

Exemple de Payload Webhook

Cas d’Utilisation

Paiements E-commerce

Services d’Abonnement

Transactions de Marketplace

Services de Transfert d’Argent

Bonnes Pratiques

Gestion des Comptes

Comptes Multiples

Sécurité

Gestion des Erreurs

Exemple de Réponse d’Erreur

Support et Ressources

Obtenir de l’Aide