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

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 → 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. Le tableau ci-dessous montre les stablecoins et les blockchains que couvre chaque devise prise en charge :

Fiat Currency	USDC Blockchains	USDT Blockchains	EURC Blockchains
COP	Ethereum, Polygon	Ethereum	—
GHS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
INR	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
KES	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
NGN	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
TZS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
UGX	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base

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

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

Operation	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}`
Regenerate	`POST /v2/wallets/{id}/virtual-accounts/{virtualAccountId}/regenerate`

Endpoints Child Address

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

Parameter	In	Required	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.

Parameter	Type	Required	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"
    }
  }
}

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

Parameter	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

Parameter	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

Parameter	Type	Required	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

Parameter	Type	Required	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. Pour les comptes de type AUTO_FUNDING, vous recevrez des notifications à chaque étape du flux de paiement.

Événements Webhook

deposit.processing — Déclenché immédiatement lorsque le paiement en fiat est reçu. Le processus d’émission est sur le point de commencer.
deposit.success — Déclenché lorsque le stablecoin a été émis et transféré vers la wallet ou l’adresse liée.
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",
    "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 la configuration des webhooks, la structure du payload et la gestion des événements, consultez la documentation des Webhooks.

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.

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

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

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

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.

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 :

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

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

​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

​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

​Comportement de l’Auto-Funding

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

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

Paiements e-commerce