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 Formulaire de Due Diligence (voir Exigences de Conformité ci-dessous).

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.

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 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//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": "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": "[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": "2025-01-21T22:15:55.746Z",
    "updatedAt": "2025-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": "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

{
  "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.

Prochaines Étapes

Une fois que cNGN est dans votre portefeuille :

Swap - Convertissez cNGN en USDT, USDC ou d’autres stablecoins à la demande
Auto-Settlement - 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

{
  "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 : [email protected]
Chat en direct : Disponible sur le tableau de bord
Référence API : API Comptes Virtuels

Besoin de support pour des stablecoins ou devises supplémentaires ? Contactez [email protected].

Démarrage

Essentiels

​Prérequis

​Comment Ça Fonctionne

Création de Compte

Réception de Paiement

Financement Automatique

Gestion des Fonds

​Flux de Financement Automatique

​1. Réception du Paiement

​2. Émission Automatique

​3. Transfert Blockchain

​Exigences de Conformité

​Documents Requis

​Soumettre la Demande

​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

​Prochaines Étapes

​Bonnes Pratiques

​Gestion des Comptes

​Comptes Multiples

​Sécurité

​Gestion des Erreurs

​Exemple de Réponse d’Erreur

​Support

Prérequis

Comment Ça Fonctionne

Flux de Financement Automatique

1. Réception du Paiement

2. Émission Automatique

3. Transfert Blockchain

Exigences de Conformité

Documents Requis

Soumettre la Demande

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

Prochaines Étapes

Bonnes Pratiques

Gestion des Comptes

Comptes Multiples

Sécurité

Gestion des Erreurs

Exemple de Réponse d’Erreur

Support