Retrait en Fiat - Blockradar

En résumé
L’API de Retrait en Fiat de Blockradar vous permet de convertir des stablecoins compatibles en monnaie fiat et de transférer les fonds vers des comptes bancaires. Vous pouvez récupérer les actifs pris en charge, valider des comptes bancaires, obtenir des devis et exécuter des retraits depuis des master wallets ou des child addresses.

Interface de Retrait en Fiat de Blockradar

Prérequis

Avant d’utiliser le Retrait en Fiat, assurez-vous d’avoir :

Exigence de conformité

Complétez l’intégration partenaire avant de demander l’accès au Retrait en Fiat (consultez Exigences de conformité ci-dessous).

Clé d'API

Obtenez votre clé d’API depuis le Tableau de bord Blockradar. Allez dans Developers pour en générer une.

Wallet créée

Créez une wallet via le tableau de bord. Vous aurez besoin du walletId pour les opérations de retrait.

Asset ID

Récupérez les actifs fiat pris en charge avec Get Supported Assets.

Coordonnées bancaires

Recueillez un identifiant de compte valide et un identifiant d’institution (code bancaire).

Comment cela fonctionne

Le Retrait en Fiat suit une séquence simple :

Découvrir les actifs

Récupérez les actifs pris en charge pour les retraits.

Obtenir les devises fiat

Récupérez toutes les devises prises en charge.

Obtenir les taux

Récupérez le taux de change actuel pour l’actif sélectionné.

Vérifier le compte

Validez les coordonnées du compte de l’institution avant d’initier un retrait.

Obtenir un devis

Estimez les frais et le taux de change pour le montant demandé.

Exécuter

Soumettez le retrait pour traitement.

Devises fiat prises en charge

Devise	Code
Shilling kényan	KES
Naira nigérian	NGN
Shilling tanzanien	TZS
Shilling ougandais	UGX
Real brésilien	BRL
Kwacha malawien	MWK

Exigences de conformité

Avant d’accéder au Retrait en Fiat, complétez le processus d’intégration de conformité applicable à la couverture des devises de paiement.

Choisissez votre parcours d’intégration

NGN (Naira) uniquement : Remplissez le formulaire d’intégration uniquement Naira.
Autres devises africaines : Complétez l’intégration partenaire pour les devises africaines.

Si vous avez besoin d’accéder à la fois au NGN et à d’autres devises africaines prises en charge, complétez les deux parcours d’intégration.

Exigence d’approbation

L’accès au Retrait en Fiat est activé après examen et approbation de la conformité pour le parcours d’intégration choisi.

Master Wallet vs Child Address

Le Retrait en Fiat est disponible à deux niveaux :

Master Wallet

Effectuez des retraits depuis la master wallet. Idéal pour les opérations de trésorerie.

Child Address

Effectuez des retraits depuis une child address spécifique. Utile pour les flux par utilisateur.

Endpoints

Opération	Master Wallet	Child Address
Get Supported Assets	`GET /v1/wallets/{walletId}/withdraw/fiat/assets`	—
Get Institutions	`GET /v1/wallets/{walletId}/withdraw/fiat/institutions`	—
Get Exchange Rates	`GET /v1/wallets/{walletId}/withdraw/fiat/rates`	—
Get Currencies	`GET /v1/wallets/{walletId}/withdraw/fiat/currencies`	—
Verify Institution Account	`POST /v1/wallets/{walletId}/withdraw/fiat/institution-account-verification`	—
Get Quote	`POST /v1/wallets/{walletId}/withdraw/fiat/quote`	`POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/quote`
Execute	`POST /v1/wallets/{walletId}/withdraw/fiat/execute`	`POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/execute`

Flux typique

Récupérez les actifs pris en charge pour choisir la stablecoin à retirer.
Listez les institutions et sélectionnez un identifiant de banque/institution.
Vérifiez le compte pour confirmer le nom et les coordonnées du compte.
Obtenez un devis pour afficher les frais et le taux avant l’exécution.
Exécutez le retrait et suivez son statut dans votre système.

Étape 1 : Obtenir un devis

Récupérez toujours un devis avant d’exécuter un retrait afin de pouvoir afficher le taux et les frais à l’utilisateur.

Paramètres de la requête

Paramètre	Type	Requis	Description
`assetId`	string	Oui	ID de l’actif stablecoin à retirer
`amount`	string	Oui	Montant à retirer dans les unités de l’actif
`currency`	string	Oui	Devise fiat de destination (ex. : `NGN`)
`accountIdentifier`	string	Oui	Numéro ou identifiant du compte bancaire
`institutionIdentifier`	string	Oui	Code de la banque/institution

Exemple de devis

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/fiat/quote \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "amount": "1000",
    "currency": "NGN",
    "accountIdentifier": "0023103996",
    "institutionIdentifier": "SBICNGLA"
  }'

Étape 2 : Exécuter le retrait

Une fois le devis accepté, exécutez le retrait avec les mêmes informations.

Paramètres de la requête

Paramètre	Type	Requis	Description
`assetId`	string	Oui	ID de l’actif stablecoin à retirer
`amount`	string	Oui	Montant à retirer dans les unités de l’actif
`currency`	string	Oui	Devise fiat de destination (ex. : `NGN`)
`accountIdentifier`	string	Oui	Numéro ou identifiant du compte bancaire
`institutionIdentifier`	string	Oui	Code de la banque/institution
`reference`	string	Non	Référence client pour idempotence/suivi
`metadata`	object	Non	Métadonnées clé-valeur attachées à la transaction
`note`	string	Non	Note lisible par l’humain pour ce retrait

Exemple d’exécution

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/fiat/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "amount": "1000",
    "currency": "NGN",
    "accountIdentifier": "8034007516",
    "institutionIdentifier": "OPAYNGPC",
    "reference": "WD-20260303-001",
    "metadata": {
      "source": "payroll",
      "initiatedBy": "treasury-bot"
    },
    "note": "March payroll payout"
  }'

Réponse de l’exécution

{
  "status": true,
  "message": "Successful",
  "data": {
    "id": "db53c3ef-5643-4f98-92cf-d02aef300f45",
    "reference": "WD-20260303-001",
    "senderAddress": "0x969838345E5cd5F755DfcADB57e72F5d23271e48",
    "recipientAddress": "0x30F6A8457F8E42371E204a9c103f2Bd42341dD0F",
    "tokenAddress": "0x46C85152bFe9f96829aA94755D9f915F9B10EF5F",
    "amount": "1000",
    "amountPaid": "1000",
    "amountUSD": "0.68",
    "rateUSD": "0.00068",
    "fee": "2",
    "currency": "NGN",
    "toAmount": "1000.00",
    "toCurrency": "NGN",
    "status": "PENDING",
    "processingStatus": "PENDING",
    "processingProviderReference": null,
    "processingReason": null,
    "type": "OFFRAMP",
    "createdChannel": "api",
    "network": "mainnet",
    "chainId": null,
    "note": "March payroll payout",
    "metadata": {
      "source": "payroll",
      "initiatedBy": "treasury-bot"
    },
    "beneficiary": {
      "id": "4dd8d16e-8550-4f51-84a1-60df9c608c5d",
      "name": "JOHN DOE",
      "type": "FIAT",
      "isActive": true,
      "institutionIdentifier": "OPAYNGPC",
      "institutionAccountIdentifier": "8034007516",
      "currency": "NGN"
    }
  }
}

Webhooks

Suivez le statut du retrait avec les événements webhook suivants :

Événement	Description
`offramp.processing`	Le retrait est en cours de traitement
`offramp.success`	Retrait effectué avec succès
`offramp.failed`	Le retrait a échoué

Exemple de payload de webhook

{
  "event": "offramp.processing",
  "data": {
    "id": "d2b985da-7f7e-4494-a6bc-0e675d50eed3",
    "reference": "EVF2g9X70Sj4hoX3ma8l",
    "senderAddress": "0x969838345E5cd5F755DfcADB57e72F5d23271e48",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.5",
    "amountPaid": "0.5",
    "amountUSD": "0.4998",
    "rateUSD": "0.9996",
    "fee": "0",
    "feeUSD": null,
    "currency": "USD",
    "toCurrency": "NGN",
    "status": "PROCESSING",
    "processingStatus": "SUCCESS",
    "processingProviderReference": "0x25003cb8356c92e3c296e7dd384ead681c5f57fb6182760fa4178750464ffd35",
    "processingReason": null,
    "type": "OFFRAMP",
    "createdChannel": "api",
    "network": "mainnet",
    "chainId": 8453,
    "metadata": null,
    "toAmount": "711.21",
    "rate": "1422.42",
    "beneficiary": {
      "id": "4dd8d16e-8550-4f51-84a1-60df9c608c5d",
      "name": "JOHN DOE",
      "type": "FIAT",
      "isActive": true,
      "reference": "d7dd5c7cf57acb5e2ff62eb23bceaca84d5dad6e62fec3d3836f20cfa1ea735c",
      "institutionIdentifier": "OPAYNGPC",
      "institutionAccountIdentifier": "8030303030",
      "currency": "NGN"
    }
  }
}

Exemple de flux complet

Voici une implémentation complète montrant le flux vérifier → devis → exécuter :

async function executeFiatWithdrawal({
  walletId,
  currency,
  accountIdentifier,
}) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = "https://api.blockradar.co/v1";
  const headers = { "x-api-key": apiKey };

  // Step 1: Get supported assets
  const assetsRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/assets`,
    { headers },
  ).then((r) => r.json());

  // Pick the first asset (example)
  const assetId = assetsRes.data?.[0]?.asset?.id;

  // Step 2: Get supported currencies
  const currenciesRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/currencies`,
    { headers },
  ).then((r) => r.json());

  console.log("Supported currencies:", currenciesRes.data);

  // Step 3: Get institutions for the currency
  const institutionsRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/institutions?currency=${currency}`,
    { headers },
  ).then((r) => r.json());

  // Pick the first institution (example)
  const institutionIdentifier = institutionsRes.data?.[0]?.code;

  // Step 4: Verify account
  const verification = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/institution-account-verification`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        accountIdentifier,
        currency,
        institutionIdentifier,
      }),
    },
  ).then((r) => r.json());

  console.log("Account name:", verification.data?.accountName);

  // Step 5: Get exchange rate (optional)
  const amount = "1000";
  const ratesRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/rates?currency=${currency}&assetId=${assetId}&amount=${amount}`,
    { headers },
  ).then((r) => r.json());

  console.log("Rate:", ratesRes.data);

  // Step 6: Get quote
  const quote = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/quote`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        assetId,
        amount,
        currency,
        accountIdentifier,
        institutionIdentifier,
      }),
    },
  ).then((r) => r.json());

  console.log("Estimated arrival:", quote.data?.estimatedArrivalTime);
  console.log("Network fee:", quote.data?.networkFee);

  // Step 7: Execute (after user confirmation)
  const execution = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/execute`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        assetId,
        amount,
        currency,
        accountIdentifier,
        institutionIdentifier,
        reference: "WD-20260303-001",
        metadata: { source: "payroll", initiatedBy: "treasury-bot" },
        note: "March payroll payout",
      }),
    },
  ).then((r) => r.json());

  console.log("Withdrawal initiated:", execution.data?.id);
  console.log("Status:", execution.data?.status);

  // Step 8: Listen for webhook to confirm completion
  return execution.data;
}

// Usage
executeFiatWithdrawal({
  walletId: "wallet-uuid",
  currency: "NGN",
  accountIdentifier: "0023103996",
});

Réponses d’erreur

Coordonnées bancaires invalides

{
  "message": "Institution not supported",
  "statusCode": 400
}

Devise non prise en charge

{
  "message": "Currency not supported",
  "statusCode": 400
}

Actif non pris en charge

{
  "message": "Asset not supported",
  "statusCode": 404
}

Fonctionnalité non activée

{
  "message": "Fiat withdrawal feature is not enabled for this business, please contact support via the live chat or email support for more information",
}

Solde insuffisant

{
  "message": "Insufficient token balance for withdrawal",
  "statusCode": 400,
}

Solde natif insuffisant

{
  "message": "Insufficient native balance for gas fees",
  "statusCode": 400
}

Solde insuffisant sur la Master Wallet

{
  "message": "Insufficient master balance for gas top-up",
  "statusCode": 400
}

Bonnes pratiques

Expérience utilisateur

Vérifiez d’abord les comptes : Confirmez toujours le nom du compte avant d’afficher un devis
Affichez le coût total : Présentez le taux de change, les frais réseau et le montant total
Mettez en avant l’état de traitement : Utilisez les webhooks pour mettre à jour les utilisateurs en temps réel

Sécurité

Validez les entrées : Assurez-vous que la devise, l’institution et les identifiants de compte sont bien formés
Utilisez des références : Suivez les retraits avec une reference unique
Confirmez via les webhooks : Considérez offramp.success comme la source de vérité finale

Performances

Mettez en cache les listes d’institutions : Rafraîchissez périodiquement plutôt qu’à chaque requête
Réutilisez les métadonnées d’actifs : Mettez en cache les actifs et devises pris en charge
Réessayez en cas d’erreurs transitoires : Utilisez un backoff exponentiel pour les réponses 5xx

Référence de l’API

Endpoint	Description
Get Supported Assets	Lister les actifs stablecoin pris en charge
Get Institutions	Lister les institutions par devise
Get Exchange Rates	Récupérer le taux de change pour un devis
Get Currencies	Lister les devises fiat prises en charge
Verify Institution Account	Vérifier les coordonnées du compte bancaire
Master Wallet Quote	Obtenir un devis depuis la master wallet
Master Wallet Execute	Exécuter un retrait depuis la master wallet
Child Address Quote	Obtenir un devis depuis une child address
Child Address Execute	Exécuter un retrait depuis une child address

Support

E-mail : [email protected]
Documentation : Référence de l’API

Démarrage

Portefeuilles

Encaissements

Paiements

Convertir et Gérer

Conformité et Outils

Documentation Index

​Prérequis

​Comment cela fonctionne

Découvrir les actifs

Obtenir les devises fiat

Obtenir les taux

Vérifier le compte

Obtenir un devis

Exécuter

​Devises fiat prises en charge

​Exigences de conformité

​Choisissez votre parcours d’intégration

​Exigence d’approbation

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Flux typique

​Étape 1 : Obtenir un devis

​Paramètres de la requête

​Exemple de devis

​Étape 2 : Exécuter le retrait

​Paramètres de la requête

​Exemple d’exécution

​Réponse de l’exécution

​Webhooks

​Exemple de payload de webhook

​Exemple de flux complet

​Réponses d’erreur

​Bonnes pratiques

​Expérience utilisateur

​Sécurité

​Performances

​Référence de l’API

​Support

Prérequis

Comment cela fonctionne

Devises fiat prises en charge

Exigences de conformité

Choisissez votre parcours d’intégration

Exigence d’approbation

Master Wallet vs Child Address

Endpoints

Flux typique

Étape 1 : Obtenir un devis

Paramètres de la requête

Exemple de devis

Étape 2 : Exécuter le retrait

Paramètres de la requête

Exemple d’exécution

Réponse de l’exécution

Webhooks

Exemple de payload de webhook

Exemple de flux complet

Réponses d’erreur

Bonnes pratiques

Expérience utilisateur

Sécurité

Performances

Référence de l’API

Support