Déposer du Fiat - Blockradar

v2 · Recommandé
v1 · Legacy

En résumé
Les Comptes Virtuels permettent à vos clients de recevoir du fiat via des virements bancaires traditionnels, qui sont automatiquement convertis en stablecoins sur la blockchain. Le flux v2 découvre les actifs et devises disponibles pour votre wallet, renvoie un schéma décrivant exactement ce dont chaque corridor a besoin, et crée des comptes virtuels liés à une master wallet ou une child address, à travers plusieurs devises et stablecoins.

Les exigences v2 renvoient un JSON Schema décrivant les informations dont un corridor a besoin. Lorsque additionalDataRequired vaut true, utilisez le guide Formulaires dynamiques pour collecter, valider et soumettre les champs sous forme d’additionalData. Le flux v1 est disponible dans l’onglet v1 · Legacy, mais n’est plus recommandé.

Prérequis

Avant d’utiliser les Comptes Virtuels, assurez-vous de disposer de :

Clé API

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

Wallet créée

Créez une wallet via le guide Créer une Master Wallet ou le tableau de bord. Vous aurez besoin du walletId pour les opérations sur les comptes virtuels.

Conformité approuvée

Complétez le processus de Diligence Raisonnable sur le Tableau de bord : My Wallets → Settings → Compliance. Les exigences de conformité et les processus d’approbation varient selon la géographie ; vous n’avez donc besoin de compléter que celles correspondant aux rails locaux utilisés par votre produit.

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 tableau de bord.

Environnement Mainnet

La disponibilité dépend des routes de fournisseurs configurées. Les requêtes testnet n’utilisent que les routes et wallets testnet ; les requêtes mainnet n’utilisent que les routes et wallets mainnet.

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 → Settings → Subscription.

Comment ça fonctionne

Découvrir les options

Récupérez les actifs et devises disponibles pour votre wallet.

Obtenir les exigences

Récupérez le schéma décrivant ce dont le corridor sélectionné a besoin.

Créer un compte

Créez un compte virtuel avec additionalData et un label optionnel.

Auto-Funding

Le fiat entrant émet automatiquement le stablecoin équivalent vers la wallet ou l’adresse liée.

Devises fiat prises en charge

Les devises varient selon le corridor et le fournisseur. Récupérez toujours ce qui est disponible pour votre wallet avec l’endpoint de découverte plutôt que de coder la liste en dur. L’aperçu ci-dessous montre USD, EUR et les principaux corridors LATAM ; consultez le tableau complet sur la page Devises Fiat Compatibles.

Fiat Currency	USDC Blockchains	USDT Blockchains	EURC Blockchains
USD	Base, Celo, Ethereum, Polygon, Solana, Tron	Base, Celo, Ethereum, Polygon, Solana, Tron	Solana
EUR	Base, Celo, Ethereum, Polygon, Solana, Tron	Base, Celo, Ethereum, Polygon, Solana, Tron	Solana
ARS	Ethereum, Base, Polygon, Solana	Tron	—
BRL	Ethereum, Base, Polygon	Ethereum, Polygon, Tron	—
COP	Ethereum, Polygon	Ethereum	—
MXN	Ethereum, Base, Polygon, Solana	Ethereum, Polygon, Tron	Ethereum, Base, Solana

Flux Auto-Funding

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

1. Réception du paiement

Le paiement est reçu sur le compte virtuel via un virement bancaire. Un webhook onramp.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 onramp.success est déclenché à la finalisation réussie.

Actifs et devises pris en charge

v2 prend en charge plusieurs stablecoins et devises. Plutôt que de supposer une paire fixe, récupérez ce qui est disponible pour votre wallet avec l’endpoint de découverte. Par exemple, les virements bancaires NGN peuvent auto-financer le cNGN, tandis que d’autres corridors se règlent en USDC ou en d’autres actifs pris en charge.

Endpoints de l’API

Endpoints Master Wallet

Opération	Endpoint
Discover options	`GET /v2/wallets/{id}/virtual-accounts/discovery`
Get requirements	`GET /v2/wallets/{id}/virtual-accounts/requirements`
Create	`POST /v2/wallets/{id}/virtual-accounts`
List	`GET /v2/wallets/{id}/virtual-accounts`
Get one	`GET /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Update status	`PATCH /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Discover destination options	`GET /v2/wallets/{id}/virtual-accounts/{virtualAccountId}/destination/discovery`
Change destination	`PATCH /v2/wallets/{id}/virtual-accounts/{virtualAccountId}/destination`
Regenerate	`POST /v2/wallets/{id}/virtual-accounts/{virtualAccountId}/regenerate`

Endpoints Child Address

Opération	Endpoint
Create	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
List	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
Get one	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Transactions	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions`
Update status	`PATCH /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Regenerate	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate`

Étape 1: Découvrir les options

Récupérez les actifs et devises disponibles pour votre wallet pour les comptes virtuels.

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts/discovery' \
  --header 'x-api-key: <api-key>'

Discovery Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "assets": [
      {
        "asset": {
          "id": "ae455f23-3824-4125-baab-d158315cbcbd",
          "name": "USD Coin",
          "symbol": "USDC",
          "logoUrl": "https://cdn.example.com/assets/usdc.svg",
          "blockchain": {
            "id": "7773c3f9-f35d-4a36-9d85-5f4c537cd097",
            "name": "Ethereum",
            "symbol": "ETH",
            "slug": "ethereum",
            "tokenStandard": "ERC20",
            "logoUrl": "https://cdn.example.com/blockchains/ethereum.svg"
          }
        },
        "currencies": ["NGN"]
      }
    ],
    "currencies": {
      "NGN": {
        "code": "NGN",
        "currency": "NGN",
        "shortName": "Naira",
        "name": "Nigerian Naira",
        "symbol": "₦"
      }
    }
  }
}

Étape 2: Obtenir les exigences

Récupérez le schéma décrivant ce que la devise sélectionnée (et éventuellement l’actif) requiert. Interprétez-le et complétez-le avec Formulaires dynamiques.

Paramètre	In	Requis	Description
`currency`	query	Oui	Code de devise ISO 4217
`assetId`	query	Non	Actif stablecoin qui reçoit les règlements
`customerId`	query	Non	Identifiant de client existant, lorsque le fournisseur en exige un
`provider`	query	Non	Slug du fournisseur. Omettez-le pour laisser Blockradar router automatiquement

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts/requirements?currency=NGN&assetId=ae455f23-3824-4125-baab-d158315cbcbd' \
  --header 'x-api-key: <api-key>'

Requirements Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "supported": true,
    "unlocked": true,
    "additionalDataRequired": true,
    "additionalDataSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "title": "Bank account details",
      "properties": {
        "bvn": { "type": "string", "title": "BVN", "minLength": 11, "maxLength": 11 },
        "dateOfBirth": { "type": "string", "title": "Date of birth", "format": "date" }
      },
      "required": ["bvn", "dateOfBirth"],
      "additionalProperties": false
    },
    "provider": "example-provider"
  }
}

Si additionalDataRequired vaut false, vous pouvez ignorer la collecte d’additionalData et créer le compte directement. Utilisez le provider renvoyé ici lorsque vous créez le compte.

Étape 3: Créer un compte virtuel

Créez un compte virtuel pour une master wallet ou une child address. Envoyez l’objet additionalData validé construit à partir du schéma des exigences.

Paramètre	Type	Requis	Description
`provider`	string	Oui	Slug du fournisseur résolu à partir du flux d’exigences
`currency`	string	Oui	Devise ISO 4217 du compte virtuel
`assetId`	string	Non	Actif stablecoin qui reçoit les règlements
`customerId`	string	Non	Identifiant de client existant, lorsque le fournisseur en exige un
`additionalData`	object	Non	Valeurs collectées et validées par rapport à `additionalDataSchema`
`label`	string	Non	Votre libellé d’affichage pour le compte virtuel (100 caractères max.)

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "provider": "example-provider",
    "currency": "NGN",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "label": "Ada collection account",
    "additionalData": {
      "bvn": "12345678901",
      "dateOfBirth": "1992-04-18"
    }
  }'

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "provider": "example-provider",
    "currency": "NGN",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "label": "Ada collection account",
    "additionalData": {
      "bvn": "12345678901",
      "dateOfBirth": "1992-04-18"
    }
  }'

Exemple de réponse

{
  "statusCode": 201,
  "message": "Virtual account created successfully",
  "data": {
    "created": true,
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "institutionAddress": null,
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  }
}

Changer la destination du compte virtuel

Les fournisseurs qui prennent en charge les changements de destination peuvent diriger un compte virtuel existant vers une autre master wallet ou child address sans remplacer ses coordonnées bancaires.Commencez par découvrir les destinations prises en charge par le fournisseur actuel et la devise fiat du compte virtuel :

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{currentWalletId}/virtual-accounts/{virtualAccountId}/destination/discovery' \
  --header 'x-api-key: <api-key>'

La réponse regroupe les actifs de règlement pris en charge par wallet. supported: false signifie que le fournisseur actuel ne prend pas en charge le changement de destination. Les options de destination correspondent toujours à l’environnement de la requête : les requêtes testnet ne renvoient que des wallets et routes testnet, tandis que les requêtes mainnet ne renvoient que des wallets et routes mainnet.

Destination Discovery Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "supported": true,
    "provider": "noah",
    "destinations": [
      {
        "wallet": {
          "id": "0f49ce21-6222-4f68-a91d-c05c798ef067",
          "name": "Treasury Wallet",
          "network": "mainnet",
          "blockchain": {
            "id": "7773c3f9-f35d-4a36-9d85-5f4c537cd097",
            "name": "Ethereum",
            "symbol": "ETH",
            "slug": "ethereum",
            "tokenStandard": "ERC20",
            "logoUrl": "https://cdn.example.com/blockchains/ethereum.svg"
          }
        },
        "assets": [
          {
            "asset": {
              "id": "ae455f23-3824-4125-baab-d158315cbcbd",
              "name": "USD Coin",
              "symbol": "USDC"
            },
            "currencies": ["USD"]
          }
        ]
      }
    ]
  }
}

Après avoir choisi une wallet et un actif, récupérez éventuellement les child addresses de la wallet avec les endpoints d’adresses existants. Omettez addressId pour utiliser l’adresse de la master wallet.

curl --request PATCH \
  --url 'https://api.blockradar.co/v2/wallets/{currentWalletId}/virtual-accounts/{virtualAccountId}/destination' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "walletId": "0f49ce21-6222-4f68-a91d-c05c798ef067",
    "addressId": "b47a29dc-f0d8-4814-b352-91f035872ba0",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd"
  }'

L’API revalide la destination par rapport aux routes de conversion actives du fournisseur avant d’appliquer le changement. Elle renvoie 409 Conflict lorsque le compte virtuel utilise déjà la destination sélectionnée. Une incohérence dans la confirmation du fournisseur renvoie 502 Bad Gateway, et la destination locale reste inchangée.

Lister les comptes virtuels

L’endpoint de listage renvoie une liste paginée de comptes virtuels. Utilisez les paramètres de requête pour rechercher, filtrer par état d’activation et filtrer par plage de dates.

Paramètres de requête

Paramètre	Type	Description
`isActive`	boolean	Filtrer par état d’activation (`true` ou `false`)
`search`	string	Rechercher par référence, libellé, nom de compte ou numéro de compte
`startDate`	string	Date de début ISO 8601 incluse. Requise uniquement lorsque `endDate` est fournie
`endDate`	string	Date de fin ISO 8601 incluse. Requise uniquement lorsque `startDate` est fournie
`page`	integer	Numéro de page basé sur 1 (par défaut : 1)
`limit`	integer	Enregistrements par page, max 100 (par défaut : 10)

Response Example

{
  "statusCode": 200,
  "message": "Virtual accounts retrieved successfully",
  "data": [
    {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "institutionAddress": null,
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

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 child addresses.

Transactions des comptes virtuels

Récupérez les transactions associées à un compte virtuel avec l’endpoint des transactions pour child address. Chaque événement d’auto-funding est également transmis via les webhooks.

Paramètres de requête

Paramètre	Type	Description
`page`	integer	Numéro de page basé sur 1 (par défaut : 1)
`limit`	integer	Enregistrements par page, max 100 (par défaut : 10)

Response Example

{
  "statusCode": 200,
  "message": "Virtual account transactions retrieved successfully",
  "data": [
    {
      "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
      "reference": "auto-funding-09026725110701402449700167083590131815",
      "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4",
      "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "tokenAddress": "0x46C85152bFe9f96829aA94755D9f915F9B10EF5F",
      "amount": "50.0",
      "amountPaid": "50.0",
      "amountUSD": "50.0",
      "rateUSD": "1.0",
      "currency": "NGN",
      "hash": "0xbe0c9a4dd314b6220c4eaae218003e753e948ce6183b5b92c764501e1b4e7c0a",
      "confirmed": true,
      "status": "SUCCESS",
      "processingStatus": "SUCCESS",
      "type": "DEPOSIT",
      "note": "Auto funding of 50.0 cNGN",
      "createdAt": "2026-01-22T22:29:28.679Z",
      "updatedAt": "2026-01-22T23:15:21.849Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

Mise à jour des comptes virtuels

Activez ou désactivez un compte virtuel 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 child addresses.

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

Request Example

{
  "isActive": false
}

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.

Régénération des comptes virtuels

L’endpoint de régénération crée un nouveau compte virtuel pour un client tout en désactivant l’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 un autre fournisseur

Paramètres de régénération

Paramètre	Type	Requis	Description
`provider`	string	Oui	Slug du fournisseur pour le compte de remplacement
`currency`	string	Oui	Devise ISO 4217 du compte virtuel
`reason`	string	Oui	Motif pour lequel un compte de remplacement est requis
`assetId`	string	Non	Actif stablecoin qui reçoit les règlements
`customerId`	string	Non	Identifiant de client existant
`additionalData`	object	Non	Valeurs validées par rapport au schéma des exigences
`label`	string	Non	Votre libellé d’affichage pour le compte virtuel

Request Example

{
  "provider": "example-provider",
  "currency": "NGN",
  "reason": "The previous account was closed by the institution.",
  "label": "Ada collection account"
}

L’opération de régénération désactive le compte virtuel existant et en crée un nouveau. L’historique des transactions du compte d’origine est conservé et reste consultable.

Webhooks

Les comptes virtuels déclenchent des événements webhook lorsque les paiements sont reçus et traités. Le règlement fiat-vers-crypto utilise la famille unifiée d’événements de transaction onramp.*.

Événements Webhook

onramp.processing — Déclenché lorsque le paiement en fiat est détecté et que le règlement commence.
onramp.success — Déclenché lorsque l’actif de destination est réglé sur la wallet ou l’adresse liée.
onramp.failed — Déclenché si l’onramp ne peut pas être finalisé.
onramp.cancelled — Déclenché si l’onramp est annulé avant sa finalisation.

Exemple de payload Webhook

{
  "event": "onramp.success",
  "data": {
    "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
    "reference": "09026725110701402449700167083590131815",
    "amount": "75000",
    "currency": "NGN",
    "toAmount": "50.0",
    "toCurrency": "USDC",
    "status": "SUCCESS",
    "type": "ONRAMP",
    "network": "mainnet",
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "accountNumber": "0123456789",
      "bankName": "Example Bank"
    },
    "wallet": {
      "id": "4465468a-3c36-4536-918a-91d689e18a74",
      "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 le payload de référence, les règles de relation avec la source et la gestion des événements, consultez Webhooks de transaction onramp.

Et après

Une fois le stablecoin dans votre wallet :

Swap — Convertissez en USDT, USDC ou d’autres stablecoins à la demande
Auto-Settlement — Convertissez automatiquement en USDT/USDC à chaque dépôt

Cas d’usage

Paiements e-commerce

Créez des comptes virtuels pour que les clients reçoivent des paiements pour des produits ou services, automatiquement convertis en stablecoins pour votre système de paiement basé sur la blockchain.

Services d’abonnement

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

Transactions de marketplace

Activez des transactions où les clients envoient 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 monnaie locale, automatiquement convertis en stablecoins pour les transferts transfrontaliers.

Bonnes pratiques

Gestion des comptes

Utilisez le schéma des exigences : Ne collectez que les champs du schéma d’exigences actuel. Ne codez pas en dur les champs d’onboarding — consultez Formulaires dynamiques.
Réutilisez le fournisseur renvoyé : Créez avec le provider renvoyé par la requête d’exigences.
Libellez vos comptes : Définissez un label pour rendre les comptes recherchables et faciles à réconcilier.
Activation des comptes : Désactivez les comptes que vous n’êtes pas prêt à financer ; réactivez-les le moment venu.
Documentez les motifs de régénération : Fournissez toujours un reason clair lors de la régénération à des fins d’audit.

Sécurité

Vérification du client : Vérifiez les informations du client avant de créer des comptes virtuels.
Préservez les chaînes : Envoyez les identifiants et codes sous forme de chaînes pour éviter toute perte de précision.
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.

Status Code	Error	Description
`400`	Bad Request	Paramètres de requête invalides ou `additionalData` mal formaté
`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

{
  "statusCode": 400,
  "message": "Invalid additional data for bvn: bvn does not match the expected format"
}

Référence de l’API

v2 (Recommandé)

Endpoint	Description
Discover Options	Lister les actifs et devises disponibles
Get Requirements	Récupérer le schéma des champs pour un corridor
Master Wallet Create	Créer un compte virtuel pour une master wallet
Master Wallet List	Lister les comptes virtuels d’une master wallet
Master Wallet Get One	Récupérer un compte virtuel spécifique
Master Wallet Update	Activer ou désactiver un compte virtuel
Master Wallet Regenerate	Régénérer un compte virtuel
Child Address Create	Créer un compte virtuel pour une child address
Child Address List	Lister les comptes virtuels d’une child address
Child Address Get One	Récupérer un compte virtuel spécifique
Child Address Transactions	Lister les transactions d’un compte virtuel
Child Address Update	Activer ou désactiver un compte virtuel
Child Address Regenerate	Régénérer un compte virtuel

Support

E-mail : [email protected]
Chat en direct : Disponible sur le tableau de bord
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].

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.

Les exigences des comptes virtuels peuvent varier selon le fournisseur, la devise et le client. Lorsqu’un endpoint renvoie un schéma de formulaire, utilisez le guide Formulaires dynamiques pour collecter et valider les informations requises.

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 depuis le dashboard (voir Créer un Portefeuille Principal). Vous aurez besoin du walletId pour les opérations sur les comptes virtuels.

Conformité approuvée

Effectuez le processus de Diligence Raisonnable sur le Tableau de bord : My wallets > Settings > Compliance

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

Prise en charge des stablecoins

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 onramp.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 onramp.success est déclenché à la finalisation réussie.

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"
  }
}

Webhooks

Événements Webhook

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

onramp.processing - Déclenché lorsque le paiement en fiat est détecté et que le règlement commence.
onramp.success - Déclenché lorsque l’actif de destination est réglé sur la wallet ou l’adresse liée.
onramp.failed - Déclenché si l’onramp ne peut pas être finalisé.
onramp.cancelled - Déclenché si l’onramp est annulé avant sa finalisation.

Exemple de payload Webhook

{
  "event": "onramp.success",
  "data": {
    "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
    "reference": "09026725110701402449700167083590131815",
    "amount": "75000",
    "currency": "NGN",
    "toAmount": "50.0",
    "toCurrency": "USDC",
    "status": "SUCCESS",
    "type": "ONRAMP",
    "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"
    }
  }
}

Pour le payload de référence, les règles de relation avec la source et la gestion des événements, consultez Webhooks de transaction onramp.

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].

​Prérequis

​Comment ça fonctionne

Découvrir les options

Obtenir les exigences

Créer un compte

Auto-Funding

​Devises fiat prises en charge

​Flux Auto-Funding

​1. Réception du paiement

​2. Émission automatique

​3. Transfert sur la blockchain

​Actifs et devises pris en charge

​Endpoints de l’API

​Endpoints Master Wallet

​Endpoints Child Address

​Étape 1: Découvrir les options

​Étape 2: Obtenir les exigences

​Étape 3: Créer un compte virtuel

​Exemple de réponse

​Changer la destination du compte virtuel

​Lister les comptes virtuels

​Paramètres de requête

​Récupérer un compte virtuel unique

​Transactions des comptes virtuels

​Paramètres de requête

​Mise à jour des comptes virtuels

​Comportement de l’Auto-Funding

​Paramètres de mise à jour

​Régénération des comptes virtuels

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

​Webhooks

​Événements Webhook

​Exemple de payload Webhook

​Et après

​Cas d’usage

​Paiements e-commerce

​Services d’abonnement

​Transactions de marketplace

​Services de transfert de fonds

​Bonnes pratiques

​Gestion des comptes

​Sécurité

​Gestion des erreurs

​Exemple de réponse d’erreur

​Référence de l’API

​v2 (Recommandé)

​Support

​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

​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

Prérequis

Comment ça fonctionne

Devises fiat prises en charge

Flux Auto-Funding

1. Réception du paiement

2. Émission automatique

3. Transfert sur la blockchain

Actifs et devises pris en charge

Endpoints de l’API

Endpoints Master Wallet

Endpoints Child Address

Étape 1: Découvrir les options

Étape 2: Obtenir les exigences

Étape 3: Créer un compte virtuel

Exemple de réponse

Changer la destination du compte virtuel

Lister les comptes virtuels

Paramètres de requête

Récupérer un compte virtuel unique

Transactions des comptes virtuels

Paramètres de requête

Mise à jour des comptes virtuels

Comportement de l’Auto-Funding

Paramètres de mise à jour

Régénération des comptes virtuels

Paramètres de régénération

Webhooks

Événements Webhook

Exemple de payload Webhook

Et après

Cas d’usage

Paiements e-commerce

Services d’abonnement

Transactions de marketplace

Services de transfert de fonds

Bonnes pratiques

Gestion des comptes

Sécurité

Gestion des erreurs

Exemple de réponse d’erreur

Référence de l’API

v2 (Recommandé)

Support

Prérequis

Comment ça fonctionne

Flux Auto-Funding

1. Réception du paiement

2. Émission automatique

3. Transfert sur la blockchain

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