> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrait en Fiat

> Convertissez des stablecoins en fiat et envoyez les fonds vers des comptes bancaires

<Note>
  En résumé<br />
  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.
</Note>

<img src="https://mintcdn.com/blockradar/9k7zAm2kB6tSbuCY/images/withdraw-fiat.png?fit=max&auto=format&n=9k7zAm2kB6tSbuCY&q=85&s=17b9748b21b1ff2f7eff9779d791d44d" alt="Interface de Retrait en Fiat de Blockradar" width="2032" height="1707" data-path="images/withdraw-fiat.png" />

## Prérequis

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

<Steps>
  <Step title="Exigence de conformité">
    Complétez l'intégration partenaire avant de demander l'accès au Retrait en Fiat (consultez
    [Exigences de conformité](#exigences-de-conformite) ci-dessous).
  </Step>

  <Step title="Clé d'API">
    Obtenez votre clé d'API depuis le [Tableau de bord
    Blockradar](https://dashboard.blockradar.co). Allez dans **Developers** pour
    en générer une.
  </Step>

  <Step title="Wallet créée">
    Créez une wallet via le tableau de bord. Vous aurez besoin du `walletId` pour les
    opérations de retrait.
  </Step>

  <Step title="Asset ID">
    Récupérez les actifs fiat pris en charge avec [Get Supported
    Assets](/en/api-reference/withdraw-fiat/get-supported-assets).
  </Step>

  <Step title="Coordonnées bancaires">
    Recueillez un identifiant de compte valide et un identifiant d'institution (code bancaire).
  </Step>
</Steps>

## Comment cela fonctionne

Le Retrait en Fiat suit une séquence simple :

<CardGroup cols={2}>
  <Card title="Découvrir les actifs" icon="coins">
    Récupérez les actifs pris en charge pour les retraits.
  </Card>

  <Card title="Obtenir les devises fiat" icon="money-bill-wave">
    Récupérez toutes les devises prises en charge.
  </Card>

  <Card title="Obtenir les taux" icon="chart-line">
    Récupérez le taux de change actuel pour l'actif sélectionné.
  </Card>

  <Card title="Vérifier le compte" icon="badge-check">
    Validez les coordonnées du compte de l'institution avant d'initier un retrait.
  </Card>

  <Card title="Obtenir un devis" icon="calculator">
    Estimez les frais et le taux de change pour le montant demandé.
  </Card>

  <Card title="Exécuter" icon="paper-plane">
    Soumettez le retrait pour traitement.
  </Card>
</CardGroup>

## 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](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form).
* **Autres devises africaines** : Complétez l'[intégration partenaire pour les devises africaines](https://app.paycrest.io/partner-onboarding?referralId=blockradar).

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

### **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 :

<CardGroup cols={2}>
  <Card title="Master Wallet" icon="wallet">
    Effectuez des retraits depuis la master wallet. Idéal pour les opérations de trésorerie.
  </Card>

  <Card title="Child Address" icon="address-card">
    Effectuez des retraits depuis une child address spécifique. Utile pour les flux par utilisateur.
  </Card>
</CardGroup>

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

1. **Récupérez les actifs pris en charge** pour choisir la stablecoin à retirer.
2. **Listez les institutions** et sélectionnez un identifiant de banque/institution.
3. **Vérifiez le compte** pour confirmer le nom et les coordonnées du compte.
4. **Obtenez un devis** pour afficher les frais et le taux avant l'exécution.
5. **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

<CodeGroup>
  ```bash Curl theme={null}
  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"
    }'
  ```
</CodeGroup>

## É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

<CodeGroup>
  ```bash Curl theme={null}
  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"
    }'
  ```
</CodeGroup>

### Réponse de l'exécution

```json theme={null}
{
  "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

```json theme={null}
{
  "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 :

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="Coordonnées bancaires invalides">
    ```json theme={null}
    {
      "message": "Institution not supported",
      "statusCode": 400
    }
    ```
  </Accordion>

  <Accordion title="Devise non prise en charge">
    ```json theme={null}
    {
      "message": "Currency not supported",
      "statusCode": 400
    }
    ```
  </Accordion>

  <Accordion title="Actif non pris en charge">
    ```json theme={null}
    {
      "message": "Asset not supported",
      "statusCode": 404
    }
    ```
  </Accordion>

  <Accordion title="Fonctionnalité non activée">
    ```json theme={null}
    {
      "message": "Fiat withdrawal feature is not enabled for this business, please contact support via the live chat or email support for more information",
    }
    ```
  </Accordion>

  <Accordion title="Solde insuffisant">
    ```json theme={null}
    {
      "message": "Insufficient token balance for withdrawal",
      "statusCode": 400,
    }
    ```
  </Accordion>

  <Accordion title="Solde natif insuffisant">
    ```json theme={null}
    {
      "message": "Insufficient native balance for gas fees",
      "statusCode": 400
    }
    ```
  </Accordion>

  <Accordion title="Solde insuffisant sur la Master Wallet">
    ```json theme={null}
    {
      "message": "Insufficient master balance for gas top-up",
      "statusCode": 400
    }
    ```
  </Accordion>
</AccordionGroup>

## 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](/en/api-reference/withdraw-fiat/get-supported-assets)             | Lister les actifs stablecoin pris en charge  |
| [Get Institutions](/en/api-reference/withdraw-fiat/get-institutions)                     | Lister les institutions par devise           |
| [Get Exchange Rates](/en/api-reference/withdraw-fiat/get-exchange-rates)                 | Récupérer le taux de change pour un devis    |
| [Get Currencies](/en/api-reference/withdraw-fiat/get-currencies)                         | Lister les devises fiat prises en charge     |
| [Verify Institution Account](/en/api-reference/withdraw-fiat/verify-institution-account) | Vérifier les coordonnées du compte bancaire  |
| [Master Wallet Quote](/en/api-reference/withdraw-fiat/master-wallet-get-quote)           | Obtenir un devis depuis la master wallet     |
| [Master Wallet Execute](/en/api-reference/withdraw-fiat/master-wallet-execute)           | Exécuter un retrait depuis la master wallet  |
| [Child Address Quote](/en/api-reference/withdraw-fiat/child-address-get-quote)           | Obtenir un devis depuis une child address    |
| [Child Address Execute](/en/api-reference/withdraw-fiat/child-address-execute)           | Exécuter un retrait depuis une child address |

## Support

* **E-mail** : [support@blockradar.co](mailto:support@blockradar.co)
* **Documentation** : [Référence de l'API](/en/api-reference/withdraw-fiat/get-supported-assets)