> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt > Use this file to discover all available pages before exploring further. # Comptes Virtuels > Créez et gérez des comptes bancaires virtuels liés à des portefeuilles principaux ou des adresses enfants pour des paiements fiat-vers-stablecoin fluides 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. Comptes Virtuels ## Prérequis Avant d'utiliser l'API des Comptes Virtuels, assurez-vous d'avoir : Obtenez votre clé API depuis le [Tableau de bord Blockradar](https://dashboard.blockradar.co). Naviguez vers **Developers** pour en générer une. Créez un portefeuille via l'[API Créer Portefeuille](/fr/api-reference/wallets/create-wallet) ou le tableau de bord. Vous aurez besoin du `walletId` pour les opérations de comptes virtuels. Complétez le [Formulaire de Due Diligence](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) (voir [Exigences de Conformité](#exigences-de-conformité) ci-dessous). Demandez l'activation de la fonctionnalité des comptes virtuels après l'approbation de conformité. Contactez [support@blockradar.co](mailto:support@blockradar.co) ou utilisez le chat en direct sur le tableau de bord. Les comptes virtuels ne sont disponibles que sur **MAINNET**. Les environnements testnet ne prennent pas en charge les opérations de comptes virtuels. 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éez des comptes virtuels liés à des portefeuilles principaux ou des adresses enfants avec les informations du client. Les clients envoient des paiements fiat au compte virtuel en utilisant des virements bancaires traditionnels. Les paiements déclenchent automatiquement l'émission de l'équivalent en stablecoin. Les stablecoins émis sont transférés vers le portefeuille ou l'adresse liée pour une utilisation immédiate. ## Flux de Financement Automatique Tous les comptes virtuels utilisent `AUTO_FUNDING`, qui convertit automatiquement le fiat en stablecoin. 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 d'accéder aux comptes virtuels, complétez le processus d'intégration de conformité. ### **Documents Requis** * Certificat de Constitution * ID pour Directeurs/Actionnaires * Document de Politique KYC ### **Soumettre la Demande** Complétez le [Formulaire de Due Diligence](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) avec les détails de votre entreprise, les informations de conformité et le téléchargement de documents. ## 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/{walletId}/virtual-accounts](/fr/api-reference/virtual-accounts/master-wallet-create) – Créer un compte virtuel pour un portefeuille principal * [GET /wallets/{walletId}/virtual-accounts](/fr/api-reference/virtual-accounts/master-wallet-get-all) – Lister tous les comptes virtuels (paginé) * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/fr/api-reference/virtual-accounts/master-wallet-get-one) – Récupérer un compte virtuel spécifique * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}/transactions](/fr/api-reference/virtual-accounts/master-wallet-transactions) – Obtenir les transactions d'un compte virtuel * [PATCH /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/fr/api-reference/virtual-accounts/master-wallet-update) – Mettre à jour le statut du compte virtuel * [POST /wallets/{walletId}/virtual-accounts/{virtualAccountId}/regenerate](/fr/api-reference/virtual-accounts/master-wallet-regenerate) – Régénérer un compte virtuel ### **Endpoints de l'Adresse Enfant** * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/fr/api-reference/virtual-accounts/child-address-create) – Créer un compte virtuel pour une adresse enfant * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/fr/api-reference/virtual-accounts/child-address-get-all) – Lister tous les comptes virtuels (paginé) * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/fr/api-reference/virtual-accounts/child-address-get-one) – Récupérer un compte virtuel spécifique * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions](/fr/api-reference/virtual-accounts/child-address-transactions) – Obtenir les transactions d'un compte virtuel * [PATCH /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/fr/api-reference/virtual-accounts/child-address-update) – Mettre à jour le statut du compte virtuel * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate](/fr/api-reference/virtual-accounts/child-address-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](/fr/api-reference/virtual-accounts/master-wallet-create) pour les portefeuilles principaux ou l'[API de Création de Compte Virtuel pour les adresses enfants](/fr/api-reference/virtual-accounts/child-address-create). ### **Paramètres de Requête pour Portefeuille Principal** | 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 | | `bvn` | string | Oui | Bank Verification Number du client | | `dateOfBirth` | string | Oui | Date de naissance du client au format `yyyy-MM-dd` | ### **Exemple de Requête pour Portefeuille Principal** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "bvn": "22345678901", "dateOfBirth": "1992-08-14" } ``` ### **Paramètres de Requête pour Adresse Enfant** | 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 | | `bvn` | string | Oui | Bank Verification Number du client | | `dateOfBirth` | string | Oui | Date de naissance du client au format `yyyy-MM-dd` | ### **Exemple de Requête pour Adresse Enfant** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "bvn": "22345678901", "dateOfBirth": "1992-08-14" } ``` ### **Exemple de Réponse** ```json theme={null} { "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": "john.doe@example.com", "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** ```json theme={null} { "message": "Virtual accounts 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": null, "createdAt": "2025-01-21T22:15:55.746Z", "updatedAt": "2025-01-21T22:15:55.746Z", "customer": { "id": "3082e278-557a-44f0-9205-c2639560cd5a", "name": "John Doe", "email": "john.doe@example.com", "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](/fr/api-reference/virtual-accounts/master-wallet-get-one) ou l'[API de Récupération de Compte Virtuel pour les adresses enfants](/fr/api-reference/virtual-accounts/child-address-get-one). ### **Exemple de Réponse** ```json theme={null} { "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": "2025-01-21T22:15:55.746Z", "updatedAt": "2025-01-21T22:15:55.746Z", "customer": { "id": "3082e278-557a-44f0-9205-c2639560cd5a", "name": "John Doe", "email": "john.doe@example.com", "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** ```json theme={null} { "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": "2025-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** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "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](/fr/api-reference/virtual-accounts/master-wallet-update) ou l'[API de Mise à Jour de Compte Virtuel pour les adresses enfants](/fr/api-reference/virtual-accounts/child-address-update). ### **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** ```json theme={null} { "isActive": false } ``` ### **Exemple de Réponse** ```json theme={null} { "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 : 1. **`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. 2. **`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é. 3. **`deposit.failed`** - Déclenché si le processus d'émission ou de transfert échoue à un moment donné. 4. **`deposit.cancelled`** - Déclenché si la transaction est annulée avant son achèvement. ### **Exemple de Payload Webhook** ```json theme={null} { "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](/fr/essentials/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. ## Prochaines Étapes Une fois que cNGN est dans votre portefeuille : * **[Swap](/fr/essentials/swap)** - Convertissez cNGN en USDT, USDC ou d'autres stablecoins à la demande * **[Auto-Settlement](/fr/essentials/auto-settlements)** - Convertissez automatiquement cNGN en USDT/USDC à chaque dépôt ## 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** ```json theme={null} { "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 * **Email** : [support@blockradar.co](mailto:support@blockradar.co) * **Chat en direct** : Disponible sur le tableau de bord * **Référence API** : [API Comptes Virtuels](/fr/api-reference/virtual-accounts/master-wallet-get-all) Besoin de support pour des stablecoins ou devises supplémentaires ? Contactez [support@blockradar.co](mailto:support@blockradar.co).