Ordres de Paiement

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

Prérequis

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

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 depuis le tableau de bord (voir Créer un Portefeuille Principal). Vous aurez besoin du walletId pour les opérations d’ordres de paiement.

Conformité approuvée

Effectuez le processus de due diligence 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 du tableau de bord.

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.

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.

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.

Ordre créé

Un ordre est généré avec une référence, un montant attendu et son rail de collecte.

Compte émis

Pour le rail compte virtuel à usage unique, un compte bancaire à usage unique est joint dans paymentInstructions.

Paiement reçu

Le client paie le compte avant expiresAt ; l’ordre passe à processing puis à paid.

Règlement

La stablecoin équivalente est émise et réglée sur la wallet ou l’adresse enfant liée.

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.

Flux de création lié à une session

Commencez la création d’un ordre de paiement en demandant un devis avec assetId, currency, amount et rail. Lorsque le dépôt appartient à un client existant, incluez aussi customerId afin que le KYC fournisseur enregistré puisse être réutilisé. L’adaptateur du fournisseur déduit le corridor KYC de la devise fiat sélectionnée. Le devis renvoie un sessionId et sessionExpiresAt. La session fige la wallet, l’actif de la wallet, la devise fiat, le montant, le rail, le fournisseur, la route de conversion, le client et le corridor KYC pendant 20 minutes. Nous vous recommandons d’utiliser le sessionId renvoyé pour chaque requête suivante :

Initialisez le formulaire avec additionalDataRequirements.data lorsqu’il ne vaut pas null. Il contient les valeurs réutilisables déjà enregistrées pour le client, le fournisseur et le corridor.
Collectez les valeurs manquantes exigées par additionalDataRequirements.schema.
Si le schéma contient un x-resolution, appelez POST /v1/wallets/{id}/deposit/fiat/payment-order-requirements/resolve avec sessionId et les additionalData actuelles.
Fusionnez les valeurs résolues dans additionalData.
Créez l’ordre avec sessionId, additionalData et les éventuels champs facultatifs de l’ordre, tels que reference ou metadata.

Quote request

{
  "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
  "currency": "NGN",
  "amount": "100.00",
  "rail": "one_time_virtual_account",
  "customerId": "18d2f159-e0cd-4a45-b735-e9dfe0f7520a"
}

Quote session

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "sessionExpiresAt": "2026-09-15T15:20:00.000Z",
  "additionalDataRequirements": {
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "title": "Refund account and customer KYC"
    },
    "data": null
  }
}

Par souci de concision, seuls les champs de premier niveau du schéma sont affichés ci-dessus ; affichez le JSON Schema complet propre au fournisseur renvoyé par l’API.

Resolve requirements

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "additionalData": {
    "institutionIdentifier": "OPAYNGPC",
    "accountIdentifier": "8034007516",
    "kyc": {
      "entityType": "person",
      "personDetails": {
        "fullName": "Ada Okafor",
        "birthDate": "1992-04-18",
        "idDocument": {
          "number": "12345678901"
        },
        "taxId": {
          "value": "10987654321"
        }
      }
    }
  }
}

Create payment order

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "additionalData": {
    "institutionIdentifier": "OPAYNGPC",
    "accountIdentifier": "8034007516",
    "accountName": "Ada Okafor",
    "kyc": {
      "entityType": "person",
      "personDetails": {
        "fullName": "Ada Okafor",
        "birthDate": "1992-04-18",
        "idDocument": {
          "number": "12345678901"
        },
        "taxId": {
          "value": "10987654321"
        }
      }
    }
  },
  "reference": "dep_20260915_001"
}

L’exemple ci-dessus est un profil de personne Paycrest NGN : idDocument.number est le NIN à 11 chiffres du client et taxId.value est son BVN à 11 chiffres. Les exigences varient selon le fournisseur, le corridor et le type d’entité ; affichez donc toujours le schéma renvoyé par le devis au lieu de coder ces champs en dur. Lorsque l’ordre est créé avec un KYC inline, Blockradar l’enregistre pour le client de l’entreprise, le fournisseur sélectionné et le corridor. Un devis ultérieur avec le même customerId et le même corridor renvoie le KYC enregistré dans additionalDataRequirements.data. L’envoi d’un KYC modifié sur un ordre ultérieur met à jour le profil enregistré pour ce corridor ; aucun endpoint KYC distinct n’est nécessaire.

Ne réutilisez pas une session avec des valeurs d’actif, de devise, de montant, de rail ou de fournisseur provenant d’un autre devis. Si l’API renvoie FIAT_DEPOSIT_SESSION_EXPIRED, FIAT_DEPOSIT_SESSION_MISMATCH ou FIAT_DEPOSIT_SESSION_UNAVAILABLE, demandez un nouveau devis et recommencez la résolution des exigences.

Pour assurer la rétrocompatibilité, sessionId est facultatif. Si vous l’omettez, envoyez les valeurs d’origine assetId, currency, amount et rail dans les requêtes de résolution des exigences et de création d’ordre. Lorsque sessionId est présent, les valeurs stockées dans la session font autorité.

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

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

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

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.

Référence API

Découverte et configuration

Endpoint	Description
Get Supported Assets	Lister les actifs stablecoin disponibles pour les dépôts en fiat
Get Supported Currencies	Lister les devises fiat disponibles pour les dépôts
Get Supported Rails	Lister les rails de collecte fiat pris en charge
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	Obtenir un devis avant de créer un ordre
Master Wallet Create Payment Order	Créer un ordre de paiement pour une master wallet
List Payment Orders	Lister les ordres de paiement d’une master wallet
Get Payment Order	Récupérer un ordre de paiement unique par son identifiant
Refresh Payment Order	Actualiser un ordre pour obtenir le statut et les détails les plus récents
Cancel Payment Order	Annuler un ordre de paiement en attente

Adresse enfant

Endpoint	Description
Get Child Address Quote	Obtenir un devis avant de créer un ordre
Create Child Address Payment Order	Créer un ordre de paiement pour une adresse enfant
List Child Address Payment Orders	Lister les ordres de paiement d’une adresse enfant

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.

Démarrage

Portefeuilles

Encaissements

Paiements

Convertir et Gérer

Conformité et Outils

Prérequis

Comment ça marche

Ordre créé

Compte émis

Paiement reçu

Règlement

Statut de l’ordre

Rails de collecte

Flux de création lié à une session

Lister les ordres de paiement de la master wallet

Paramètres de requête

Exemple de réponse

Lister les ordres de paiement de l’adresse enfant

Paramètres de chemin

Paramètres de requête

Exemple de réponse

Champs de réponse

Référence API

Découverte et configuration

Master Wallet

Adresse enfant

​Prérequis

​Comment ça marche

Ordre créé

Compte émis

Paiement reçu

Règlement

​Statut de l’ordre

​Rails de collecte

​Flux de création lié à une session

​Lister les ordres de paiement de la master wallet

​Paramètres de requête

​Exemple de réponse

​Lister les ordres de paiement de l’adresse enfant

​Paramètres de chemin

​Paramètres de requête

​Exemple de réponse

​Champs de réponse

​Référence API

​Découverte et configuration

​Master Wallet

​Adresse enfant

Prérequis

Comment ça marche

Statut de l’ordre

Rails de collecte

Flux de création lié à une session

Lister les ordres de paiement de la master wallet

Paramètres de requête

Exemple de réponse

Lister les ordres de paiement de l’adresse enfant

Paramètres de chemin

Paramètres de requête

Exemple de réponse

Champs de réponse

Référence API

Découverte et configuration

Master Wallet

Adresse enfant