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

# Ordres de Paiement

> Listez et suivez les ordres de paiement des comptes virtuels à usage unique, de la création jusqu'au règlement

<Note>
  En résumé<br />
  Un ordre de paiement représente un unique encaissement fiat attendu. Lorsque vous utilisez le rail **compte virtuel à usage unique**, chaque ordre est adossé à un compte bancaire dédié, valable pour un seul paiement. Les endpoints Ordres de Paiement vous permettent de lister et de suivre chaque ordre au niveau de la master wallet ou limités à une adresse enfant spécifique.
</Note>

## Prérequis

Avant d'utiliser l'API Ordres de paiement, assurez-vous d'avoir :

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

  <Step title="Wallet créée">
    Créez une wallet via l'[API Create Wallet](/en/api-reference/wallets/create-wallet) ou le tableau de bord. Vous aurez besoin du `walletId` pour les opérations d'ordres de paiement.
  </Step>

  <Step title="Conformité approuvée">
    Effectuez le processus de due diligence sur le Tableau de bord : My wallets > Settings > Compliance
  </Step>

  <Step title="Fonctionnalité activée">
    Demandez l'activation de la fonctionnalité de comptes virtuels après l'approbation de conformité. Contactez [support@blockradar.co](mailto:support@blockradar.co) ou utilisez le chat en direct du tableau de bord.
  </Step>

  <Step title="Environnement mainnet">
    Les comptes virtuels ne sont disponibles que sur le **MAINNET**. Les environnements testnet ne prennent pas en charge les opérations de comptes virtuels.
  </Step>

  <Step title="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. Effectuez la mise à niveau depuis **Tableau de bord → Settings → Subscription**.
  </Step>
</Steps>

## Comment ça marche

Un ordre de paiement est créé chaque fois qu'un client initie un dépôt en fiat. Pour le rail `one_time_virtual_account`, Blockradar émet un nouveau compte bancaire virtuel lié à cet ordre et à son ensemble de montants. Une fois que le client paie, l'ordre progresse dans son cycle de vie et la stablecoin correspondante est émise et réglée sur la wallet ou l'adresse liée.

<CardGroup cols={2}>
  <Card title="Ordre créé" icon="plus">
    Un ordre est généré avec une référence, un montant attendu et son rail de collecte.
  </Card>

  <Card title="Compte émis" icon="building-columns">
    Pour le rail compte virtuel à usage unique, un compte bancaire à usage unique est joint dans `paymentInstructions`.
  </Card>

  <Card title="Paiement reçu" icon="credit-card">
    Le client paie le compte avant `expiresAt` ; l'ordre passe à `processing` puis à `paid`.
  </Card>

  <Card title="Règlement" icon="wallet">
    La stablecoin équivalente est émise et réglée sur la wallet ou l'adresse enfant liée.
  </Card>
</CardGroup>

## Statut de l'ordre

Chaque ordre indique son statut actuel dans le cycle de vie. Utilisez le paramètre de requête `status` pour filtrer les résultats.

| Statut       | Description                                           |
| ------------ | ----------------------------------------------------- |
| `pending`    | Ordre créé et en attente du paiement du client.       |
| `processing` | Paiement reçu et en cours de confirmation/règlement.  |
| `paid`       | Paiement confirmé et réglé avec succès.               |
| `expired`    | L'ordre n'a pas été payé avant `expiresAt`.           |
| `failed`     | Le paiement ou le règlement n'a pas pu être effectué. |
| `cancelled`  | L'ordre a été annulé avant le paiement.               |

## Rails de collecte

Le champ `rail` indique comment l'ordre est collecté. Les comptes virtuels à usage unique utilisent le rail `one_time_virtual_account`.

| Rail                       | Description                                             |
| -------------------------- | ------------------------------------------------------- |
| `one_time_virtual_account` | Un compte bancaire dédié valable pour un seul paiement. |
| `payment_link`             | Un lien de paiement hébergé.                            |
| `qr_code`                  | Un code QR scannable.                                   |

## Lister les ordres de paiement de la master wallet

Renvoie une liste paginée de tous les ordres de paiement créés sous une master wallet. Utilisez les paramètres de requête pour filtrer par statut, rail, devise, actif, plage de dates ou recherche en texte libre.

`GET /v1/wallets/{id}/deposit/fiat/orders`

### **Paramètres de requête**

| Paramètre   | Type   | Description                                                                                        |
| ----------- | ------ | -------------------------------------------------------------------------------------------------- |
| `status`    | enum   | Filtrer par statut de l'ordre : `pending`, `paid`, `processing`, `expired`, `failed`, `cancelled`. |
| `rail`      | enum   | Filtrer par rail de collecte : `one_time_virtual_account`, `payment_link`, `qr_code`.              |
| `currency`  | string | Code de devise fiat ISO 4217 (3 caractères), p. ex. `NGN`.                                         |
| `assetId`   | string | Identifiant de l'actif stablecoin (UUID).                                                          |
| `search`    | string | Rechercher par référence, libellé, nom du compte ou numéro de compte.                              |
| `startDate` | string | Date de début ISO 8601 incluse. Obligatoire avec `endDate`.                                        |
| `endDate`   | string | Date de fin ISO 8601 incluse. Obligatoire avec `startDate`.                                        |
| `page`      | number | Numéro de page en base 1 (par défaut : 1).                                                         |
| `limit`     | number | Enregistrements par page (par défaut : 10, plage : 1–100).                                         |

### **Exemple de réponse**

```json theme={null}
{
  "statusCode": 200,
  "message": "Successful",
  "data": [
    {
      "id": "80ea45ab-38b9-4506-b213-52da8bc7e825",
      "type": "deposit",
      "rail": "one_time_virtual_account",
      "reference": "dep_20260719_001",
      "status": "pending",
      "currency": "NGN",
      "amount": "100.00",
      "amountFiat": "155000.00",
      "feeFiat": "1500.00",
      "amountFiatPayable": "156500.00",
      "expiresAt": "2026-07-19T13:00:00.000Z",
      "paymentInstructions": {
        "type": "one_time_virtual_account",
        "bank": {
          "name": "Example Bank",
          "code": "999",
          "accountName": "Blockradar / Acme Ltd",
          "accountNumber": "0123456789"
        }
      },
      "asset": {
        "id": "ae455f23-3824-4125-baab-d158315cbcbd",
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "wallet": {
        "id": "4465468a-3c36-4536-918a-91d689e18a74",
        "address": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
      },
      "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
  },
  "analytics": {
    "totalOrdersCount": 1,
    "totalPendingOrdersCount": 1,
    "totalPaidOrdersCount": 0
  }
}
```

## Lister les ordres de paiement de l'adresse enfant

Renvoie les ordres de paiement limités à une seule adresse enfant. La réponse inclut les mêmes champs d'ordre ainsi que des détails supplémentaires de règlement, de fournisseur et de client.

`GET /v1/wallets/{walletId}/addresses/{addressId}/deposit/fiat/orders`

### **Paramètres de chemin**

| Paramètre   | Type   | Requis | Description                             |
| ----------- | ------ | ------ | --------------------------------------- |
| `walletId`  | string | Oui    | Identifiant de la wallet (UUID).        |
| `addressId` | string | Oui    | Identifiant de l'adresse enfant (UUID). |

### **Paramètres de requête**

| Paramètre   | Type   | Description                                                                                        |
| ----------- | ------ | -------------------------------------------------------------------------------------------------- |
| `status`    | enum   | Filtrer par statut de l'ordre : `pending`, `paid`, `processing`, `expired`, `failed`, `cancelled`. |
| `rail`      | enum   | Filtrer par rail de collecte : `one_time_virtual_account`, `payment_link`, `qr_code`.              |
| `currency`  | string | Code de devise fiat ISO 4217 (3 caractères), p. ex. `NGN`.                                         |
| `assetId`   | string | Identifiant de l'actif stablecoin (UUID).                                                          |
| `search`    | string | Rechercher par référence, libellé, nom du compte ou numéro de compte.                              |
| `startDate` | string | Date de début ISO 8601 incluse. Obligatoire avec `endDate`.                                        |
| `endDate`   | string | Date de fin ISO 8601 incluse. Obligatoire avec `startDate`.                                        |

### **Exemple de réponse**

```json theme={null}
{
  "statusCode": 200,
  "message": "Successful",
  "data": [
    {
      "id": "80ea45ab-38b9-4506-b213-52da8bc7e825",
      "type": "deposit",
      "rail": "one_time_virtual_account",
      "reference": "dep_20260719_001",
      "providerReference": "provider_order_839201",
      "transactionId": null,
      "status": "pending",
      "currency": "NGN",
      "amount": "100.00",
      "amountFiat": "155000.00",
      "feeFiat": "1500.00",
      "amountFiatPayable": "156500.00",
      "amountFiatReceived": null,
      "amountSettled": null,
      "expiresAt": "2026-07-19T13:00:00.000Z",
      "paymentInstructions": {
        "type": "one_time_virtual_account",
        "bank": {
          "name": "Example Bank",
          "code": "999",
          "accountName": "Blockradar / Acme Ltd",
          "accountNumber": "0123456789"
        },
        "paymentLink": null,
        "qrCode": null,
        "expiresAt": "2026-07-19T13:00:00.000Z",
        "metadata": null
      },
      "metadata": {
        "checkoutId": "checkout_123"
      },
      "provider": {
        "id": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
        "slug": "example-provider",
        "name": "Example Provider"
      },
      "wallet": {
        "id": "4465468a-3c36-4536-918a-91d689e18a74",
        "address": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
      },
      "address": null,
      "asset": {
        "id": "ae455f23-3824-4125-baab-d158315cbcbd",
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "customer": {
        "id": "18d2f159-e0cd-4a45-b735-e9dfe0f7520a"
      },
      "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
  },
  "links": {
    "first": "https://api.blockradar.co/v1/wallets/.../deposit/fiat/orders?page=1&limit=10",
    "previous": null,
    "next": null,
    "last": "https://api.blockradar.co/v1/wallets/.../deposit/fiat/orders?page=1&limit=10"
  },
  "analytics": {
    "totalOrdersCount": 1,
    "totalPendingOrdersCount": 1,
    "totalPaidOrdersCount": 0,
    "totalProcessingOrdersCount": 0,
    "totalExpiredOrdersCount": 0,
    "totalFailedOrdersCount": 0,
    "totalCancelledOrdersCount": 0
  }
}
```

## Champs de réponse

| Champ                 | Description                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `id`                  | Identifiant unique de l'ordre de paiement.                                                                       |
| `type`                | Type d'ordre. `deposit` pour les encaissements fiat.                                                             |
| `rail`                | Rail de collecte utilisé pour l'ordre.                                                                           |
| `reference`           | Votre référence pour l'ordre.                                                                                    |
| `status`              | Statut actuel de l'ordre dans le cycle de vie.                                                                   |
| `currency`            | Devise fiat ISO 4217 du paiement attendu.                                                                        |
| `amount`              | Montant de stablecoin à émettre.                                                                                 |
| `amountFiat`          | Valeur en fiat de l'ordre avant frais.                                                                           |
| `feeFiat`             | Frais facturés en fiat.                                                                                          |
| `amountFiatPayable`   | Montant total en fiat que le client doit payer (`amountFiat` + `feeFiat`).                                       |
| `expiresAt`           | Horodatage après lequel un ordre impayé expire.                                                                  |
| `paymentInstructions` | Comment le client paie. Contient les informations `bank` à usage unique pour le rail `one_time_virtual_account`. |
| `asset`               | L'actif stablecoin sur lequel l'ordre est réglé.                                                                 |
| `wallet`              | La master wallet à laquelle l'ordre appartient.                                                                  |
| `meta`                | Métadonnées de pagination pour l'ensemble des résultats.                                                         |
| `analytics`           | Comptes agrégés des ordres par statut.                                                                           |

<Note>
  Les champs `amountFiatReceived`, `amountSettled`, `providerReference`, `provider` et `customer` sont renvoyés sur l'endpoint d'adresse enfant et se remplissent à mesure que l'ordre progresse dans le règlement.
</Note>

***

## Référence API

### Découverte et configuration

| Endpoint                                                                                                | Description                                                      |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [Get Supported Assets](/en/api-reference/deposit-fiat/get-supported-assets)                             | Lister les actifs stablecoin disponibles pour les dépôts en fiat |
| [Get Supported Currencies](/en/api-reference/deposit-fiat/get-supported-currencies)                     | Lister les devises fiat disponibles pour les dépôts              |
| [Get Supported Rails](/en/api-reference/deposit-fiat/get-supported-rails)                               | Lister les rails de collecte fiat pris en charge                 |
| [Resolve Payment Order Requirements](/en/api-reference/deposit-fiat/resolve-payment-order-requirements) | Résoudre les champs requis pour créer un ordre sur un rail donné |

### Master Wallet

| Endpoint                                                                                                | Description                                                                |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Master Wallet Get Quote](/en/api-reference/deposit-fiat/master-wallet-get-quote)                       | Obtenir un devis avant de créer un ordre                                   |
| [Master Wallet Create Payment Order](/en/api-reference/deposit-fiat/master-wallet-create-payment-order) | Créer un ordre de paiement pour une master wallet                          |
| [List Payment Orders](/en/api-reference/deposit-fiat/master-wallet-list-payment-orders)                 | Lister les ordres de paiement d'une master wallet                          |
| [Get Payment Order](/en/api-reference/deposit-fiat/master-wallet-get-payment-order)                     | Récupérer un ordre de paiement unique par son identifiant                  |
| [Refresh Payment Order](/en/api-reference/deposit-fiat/master-wallet-refresh-payment-order)             | Actualiser un ordre pour obtenir le statut et les détails les plus récents |
| [Cancel Payment Order](/en/api-reference/deposit-fiat/master-wallet-cancel-payment-order)               | Annuler un ordre de paiement en attente                                    |

### Adresse enfant

| Endpoint                                                                                                | Description                                        |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [Get Child Address Quote](/en/api-reference/deposit-fiat/child-address-get-quote)                       | Obtenir un devis avant de créer un ordre           |
| [Create Child Address Payment Order](/en/api-reference/deposit-fiat/child-address-create-payment-order) | Créer un ordre de paiement pour une adresse enfant |
| [List Child Address Payment Orders](/en/api-reference/deposit-fiat/child-address-list-payment-orders)   | Lister les ordres de paiement d'une adresse enfant |

<Note>
  Récupérer, actualiser et annuler un ordre ne nécessitent que l'ID de l'ordre, il
  n'existe donc pas d'équivalent pour les adresses enfants. Utilisez les endpoints
  de la master wallet ci-dessus pour tout ordre, y compris ceux créés sur une
  adresse enfant.

  L'API expose également une opération **Find Fiat Deposit**
  (`POST /v1/wallets/{id}/deposit/fiat/finder`) qui localise un dépôt en fiat et
  ses détails de traitement à partir d'une référence de paiement. Elle est utile
  pour rapprocher un paiement qu'un client affirme avoir envoyé de l'ordre auquel
  il appartient.
</Note>