Déposer du Fiat - Blockradar

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

Prérequis

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

Clé API

Obtenez votre clé API depuis le Dashboard Blockradar. Accédez à Developers pour en générer une.

Wallet créée

Créez une wallet via l’API Créer une Wallet ou le dashboard. Vous aurez besoin du walletId pour les opérations sur les comptes virtuels.

Conformité approuvée

Remplissez le Formulaire de Diligence Raisonnable (voir Exigences de conformité ci-dessous).

Fonctionnalité activée

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

Environnement Mainnet

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

Prise en charge des stablecoins

Déposer du fiat et le convertir en stablecoin est une fonctionnalité payante. Assurez-vous que votre offre inclut l’accès aux stablecoins. Mettez à niveau depuis Dashboard → Paramètres → Abonnement.

Comment ça fonctionne

Création de compte

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

Réception de paiement

Les clients envoient des paiements en fiat sur le compte virtuel via des virements bancaires traditionnels.

Auto-Funding

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

Gestion des fonds

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

Flux Auto-Funding

Tous les comptes virtuels utilisent AUTO_FUNDING, qui convertit automatiquement le fiat en stablecoin. Lorsqu’un client envoie de la monnaie fiat sur un compte virtuel :

1. Réception du paiement

Le paiement est reçu sur 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 sur la blockchain

Le stablecoin émis est transféré vers la wallet ou l’adresse liée au compte virtuel. Un webhook deposit.success est déclenché à la finalisation réussie.

Exigences de conformité

Avant d’accéder aux comptes virtuels, complétez le processus d’onboarding de conformité.

Documents requis

Certificat d’incorporation
Pièce d’identité des dirigeants/actionnaires
Document de politique KYC

Soumettre la demande

Remplissez le Formulaire de Diligence Raisonnable avec les informations de votre entreprise, les informations de conformité et le téléversement des documents.

Devise prise en charge

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

Endpoints de l’API

Voici les endpoints principaux de l’API pour les opérations sur les Comptes Virtuels :

Endpoints Master Wallet

POST /wallets//virtual-accounts – Créer un compte virtuel pour une master wallet
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 d’un compte virtuel
POST /wallets//virtual-accounts//regenerate – Régénérer un compte virtuel

Endpoints 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 d’un compte virtuel
POST /wallets//addresses//virtual-accounts//regenerate – Régénérer un compte virtuel

Création de Comptes Virtuels

Vous pouvez créer des comptes virtuels à la fois pour les master wallets et pour les adresses enfants, selon votre cas d’usage. Utilisez l’API Créer un Compte Virtuel pour les master wallets ou l’API Créer un Compte Virtuel pour les adresses enfants.

Paramètres de la requête pour Master Wallet

Paramètre	Type	Requis	Description
`firstname`	string	Oui	Prénom du client (29 caractères max.)
`lastname`	string	Oui	Nom de famille du client (29 caractères max.)
`email`	string	Oui	Adresse e-mail 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 Master Wallet

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "bvn": "22345678901",
  "dateOfBirth": "1992-08-14"
}

Paramètres de la requête pour Adresse Enfant

Paramètre	Type	Requis	Description
`firstname`	string	Oui	Prénom du client (29 caractères max.)
`lastname`	string	Oui	Nom de famille du client (29 caractères max.)
`email`	string	Oui	Adresse e-mail 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

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "bvn": "22345678901",
  "dateOfBirth": "1992-08-14"
}

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",
    "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 wallet ou adresse enfant. C’est utile lorsque :

Un client a besoin de comptes distincts à des fins différentes (par exemple, épargne, paiements)
Vous souhaitez suivre séparément les paiements provenant de différentes sources
Le compte virtuel existant d’un client doit être remplacé tout en conservant l’historique

Lister les Comptes Virtuels

L’endpoint de listage renvoie 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",
      "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érer un Compte Virtuel unique

Pour récupérer un compte virtuel spécifique par ID, utilisez l’API Obtenir un Compte Virtuel pour les master wallets ou l’API Obtenir un 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",
    "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 des Comptes Virtuels

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 les détails de la source du paiement en fiat, notamment le nom de la banque de l’expéditeur, le nom du compte et la narration de la transaction 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 le compte existant. C’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 (29 caractères max.)
`lastname`	string	Oui	Nom de famille du client (29 caractères max.)
`email`	string	Oui	Adresse e-mail du client
`phone`	string	Non	Numéro de téléphone du client au format : +234XXXXXXXXXX
`reason`	string	Oui	Motif de la régénération du compte virtuel

Exemple de requête

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "reason": "Customer requested new account number"
}

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 d’origine est conservé et reste consultable.

Mise à jour des Comptes Virtuels

Vous pouvez activer ou désactiver les comptes virtuels pour contrôler le comportement de l’auto-funding. Utilisez l’API Mettre à jour un Compte Virtuel pour les master wallets ou l’API Mettre à jour un Compte Virtuel pour les adresses enfants.

Comportement de l’Auto-Funding

Comptes actifs : Les paiements reçus déclenchent l’émission automatique de stablecoins
Comptes inactifs : Les paiements sont reçus, mais l’auto-funding 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"
  }
}

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

Webhooks

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

Événements Webhook

Lorsqu’un client envoie un paiement en fiat sur un compte virtuel :

deposit.processing - Déclenché immédiatement lorsque le paiement en fiat est reçu sur 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 avec succès et transféré vers la wallet ou l’adresse liée. Cela confirme que l’ensemble du processus d’auto-funding 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 la fin.

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 tant que le compte n’aura pas été 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’usage

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 des clients, permettant des paiements récurrents via des virements bancaires traditionnels qui sont automatiquement convertis en stablecoins.

Transactions de marketplace

Activez les transactions peer-to-peer où les clients peuvent envoyer des paiements en fiat qui sont instantanément convertis en stablecoins et crédités sur leur wallet.

Services de transfert de fonds

Fournissez aux clients des comptes virtuels pour recevoir des transferts de fonds en NGN, qui sont automatiquement convertis en stablecoins pour faciliter les transferts transfrontaliers.

Et après

Une fois que cNGN est dans votre wallet :

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 le même payload de création pour les deux routes : La création de comptes virtuels pour master wallet et adresse enfant utilise les mêmes informations client (firstname, lastname, email, phone, bvn, dateOfBirth)
Format du numéro de téléphone : Pour la création de comptes virtuels, utilisez toujours le format correct (+234XXXXXXXXXX) pour les numéros de téléphone nigérians
Activation des comptes : N’activez les comptes que lorsque vous êtes prêt à traiter les paiements
Surveillez le statut des comptes : Vérifiez régulièrement le statut des comptes et gérez les comptes inactifs de manière appropriée
Documentez les motifs de régénération : Fournissez toujours des motifs clairs lors de la régénération des comptes à des fins d’audit

Comptes multiples

Planifiez la structure de vos comptes : Décidez à l’avance combien de comptes chaque client peut avoir besoin
Suivez l’historique des comptes : Lors de la régénération, conservez les références aux ID des 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 : Mettez en œuvre des contrôles d’accès appropriés pour la gestion des comptes virtuels

Gestion des erreurs

L’API renvoie 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 (par exemple, format de téléphone invalide ou détails de compte mal formatés)
`401`	Unauthorized	Clé API manquante ou invalide
`404`	Not Found	Compte virtuel ou wallet introuvable
`422`	Unprocessable Entity	Échec de la validation (par exemple, champs requis manquants)

Exemple de réponse d’erreur

{
  "message": "Validation failed",
  "statusCode": 422,
  "error": "Unprocessable Entity"
}

Support

E-mail : [email protected]
Chat en direct : Disponible sur le dashboard
Référence de l’API : API des Comptes Virtuels

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

Démarrage

Portefeuilles

Encaissements

Paiements

Convertir et Gérer

Conformité et Outils

Documentation Index

​Prérequis

​Comment ça fonctionne

Création de compte

Réception de paiement

Auto-Funding

Gestion des fonds

​Flux Auto-Funding

​1. Réception du paiement

​2. Émission automatique

​3. Transfert sur la blockchain

​Exigences de conformité

​Documents requis

​Soumettre la demande

​Devise prise en charge

​Endpoints de l’API

​Endpoints Master Wallet

​Endpoints Adresse Enfant

​Création de Comptes Virtuels

​Paramètres de la requête pour Master Wallet

​Exemple de requête pour Master Wallet

​Paramètres de la requête pour Adresse Enfant

​Exemple de requête pour Adresse Enfant

​Exemple de réponse

​Comptes Virtuels Multiples

​Lister les Comptes Virtuels

​Paramètres de requête

​Exemple de réponse

​Récupérer un Compte Virtuel unique

​Exemple de réponse

​Transactions des Comptes Virtuels

​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 de l’Auto-Funding

​Paramètres de mise à jour

​Exemple de requête

​Exemple de réponse

​Webhooks

​Événements Webhook

​Exemple de payload Webhook

​Cas d’usage

​Paiements e-commerce

​Services d’abonnement

​Transactions de marketplace

​Services de transfert de fonds

​Et après

​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 Auto-Funding

1. Réception du paiement

2. Émission automatique

3. Transfert sur la blockchain

Exigences de conformité

Documents requis

Soumettre la demande

Devise prise en charge

Endpoints de l’API

Endpoints Master Wallet

Endpoints Adresse Enfant

Création de Comptes Virtuels

Paramètres de la requête pour Master Wallet

Exemple de requête pour Master Wallet

Paramètres de la requête pour Adresse Enfant

Exemple de requête pour Adresse Enfant

Exemple de réponse

Comptes Virtuels Multiples

Lister les Comptes Virtuels

Paramètres de requête

Exemple de réponse

Récupérer un Compte Virtuel unique

Exemple de réponse

Transactions des Comptes Virtuels

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 de l’Auto-Funding

Paramètres de mise à jour

Exemple de requête

Exemple de réponse

Webhooks

Événements Webhook

Exemple de payload Webhook

Cas d’usage

Paiements e-commerce

Services d’abonnement

Transactions de marketplace

Services de transfert de fonds

Et après

Bonnes pratiques

Gestion des comptes

Comptes multiples

Sécurité

Gestion des erreurs

Exemple de réponse d’erreur

Support