Payment Orders

In a nutshell
A payment order represents a single expected fiat collection. When you use the one-time virtual account rail, each order is backed by a dedicated bank account that is valid for one payment only. The Payment Orders endpoints let you list and track every order at the master wallet level or scoped to a specific child address.

Prerequisites

Before using the Payment Orders API, ensure you have:

API Key

Get your API key from the Blockradar Dashboard. Navigate to Developers to generate one.

Wallet Created

Create a wallet via the Create Wallet API or dashboard. You’ll need the walletId for payment order operations.

Compliance Approved

Complete the Due Diligence process on the Dashboard: My wallets > Settings > Compliance

Feature Enabled

Request virtual accounts feature activation after compliance approval. Contact [email protected] or use live chat on the dashboard.

Mainnet Environment

Virtual accounts are only available on MAINNET. Testnet environments do not support virtual account operations.

Stablecoin Support

Depositing Fiat and converting it to a stablecoin is a paid feature. Ensure your account plan includes stablecoin access. Upgrade from Dashboard → Settings → Subscription.

How It Works

A payment order is created whenever a customer initiates a fiat deposit. For the one_time_virtual_account rail, Blockradar issues a fresh virtual bank account tied to that order and set of amounts. Once the customer pays, the order moves through its lifecycle and the matching stablecoin is minted and settled to the linked wallet or address.

Order Created

An order is generated with a reference, an expected amount, and its collection rail.

Account Issued

For the one-time virtual account rail, a single-use bank account is attached in paymentInstructions.

Payment Received

The customer pays the account before expiresAt; the order transitions to processing then paid.

Settlement

The stablecoin equivalent is minted and settled to the linked wallet or child address.

Order Status

Every order reports its current lifecycle status. Use the status query parameter to filter results.

Status	Description
`pending`	Order created and awaiting payment from the customer.
`processing`	Payment received and being confirmed/settled.
`paid`	Payment confirmed and settled successfully.
`expired`	Order was not paid before `expiresAt`.
`failed`	Payment or settlement could not be completed.
`cancelled`	Order was cancelled before payment.

Collection Rails

The rail field identifies how the order is collected. Single-use virtual accounts use the one_time_virtual_account rail.

Rail	Description
`one_time_virtual_account`	A dedicated bank account valid for a single payment.
`payment_link`	A hosted payment link.
`qr_code`	A scannable QR code.

Listing Master Wallet Payment Orders

Returns a paginated list of every payment order created under a master wallet. Use the query parameters to filter by status, rail, currency, asset, date range, or free-text search. GET /v1/wallets/{id}/deposit/fiat/orders

Query Parameters

Parameter	Type	Description
`status`	enum	Filter by order status: `pending`, `paid`, `processing`, `expired`, `failed`, `cancelled`.
`rail`	enum	Filter by collection rail: `one_time_virtual_account`, `payment_link`, `qr_code`.
`currency`	string	ISO 4217 fiat currency code (3 characters), e.g. `NGN`.
`assetId`	string	Stablecoin asset identifier (UUID).
`search`	string	Query by reference, label, account name, or account number.
`startDate`	string	Inclusive ISO 8601 start date. Required together with `endDate`.
`endDate`	string	Inclusive ISO 8601 end date. Required together with `startDate`.
`page`	number	One-based page number (default: 1).
`limit`	number	Records per page (default: 10, range: 1–100).

Response Example

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

Listing Child Address Payment Orders

Returns the payment orders scoped to a single child address. The response includes the same order fields plus additional settlement, provider, and customer details. GET /v1/wallets/{walletId}/addresses/{addressId}/deposit/fiat/orders

Path Parameters

Parameter	Type	Required	Description
`walletId`	string	Yes	Wallet identifier (UUID).
`addressId`	string	Yes	Child address identifier (UUID).

Query Parameters

Parameter	Type	Description
`status`	enum	Filter by order status: `pending`, `paid`, `processing`, `expired`, `failed`, `cancelled`.
`rail`	enum	Filter by collection rail: `one_time_virtual_account`, `payment_link`, `qr_code`.
`currency`	string	ISO 4217 fiat currency code (3 characters), e.g. `NGN`.
`assetId`	string	Stablecoin asset identifier (UUID).
`search`	string	Query by reference, label, account name, or account number.
`startDate`	string	Inclusive ISO 8601 start date. Required together with `endDate`.
`endDate`	string	Inclusive ISO 8601 end date. Required together with `startDate`.

Response Example

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

Response Fields

Field	Description
`id`	Unique payment order identifier.
`type`	Order type. `deposit` for fiat collections.
`rail`	Collection rail used for the order.
`reference`	Your reference for the order.
`status`	Current lifecycle status of the order.
`currency`	ISO 4217 fiat currency of the expected payment.
`amount`	Stablecoin amount to be minted.
`amountFiat`	Fiat value of the order before fees.
`feeFiat`	Fee charged in fiat.
`amountFiatPayable`	Total fiat amount the customer must pay (`amountFiat` + `feeFiat`).
`expiresAt`	Timestamp after which an unpaid order expires.
`paymentInstructions`	How the customer pays. Contains the single-use `bank` details for the `one_time_virtual_account` rail.
`asset`	The stablecoin asset the order settles into.
`wallet`	The master wallet the order belongs to.
`meta`	Pagination metadata for the result set.
`analytics`	Aggregate counts of orders by status.

The amountFiatReceived, amountSettled, providerReference, provider, and customer fields are returned on the child address endpoint and populate as the order progresses through settlement.

API Reference

Discovery & Configuration

Endpoint	Description
Get Supported Assets	List the stablecoin assets available for fiat deposits
Get Supported Currencies	List the fiat currencies available for deposits
Get Supported Rails	List the supported fiat collection rails
Resolve Payment Order Requirements	Resolve the fields required to create an order for a given rail

Master Wallet

Endpoint	Description
Master Wallet Get Quote	Get a quote before creating an order
Master Wallet Create Payment Order	Create a payment order for a master wallet
List Payment Orders	List payment orders for a master wallet
Get Payment Order	Retrieve a single payment order by its identifier
Refresh Payment Order	Refresh an order to get updated status and details
Cancel Payment Order	Cancel a pending payment order

Child Address

Endpoint	Description
Get Child Address Quote	Get a quote before creating an order
Create Child Address Payment Order	Create a payment order for a child address
List Child Address Payment Orders	List payment orders for a child address

Retrieving, refreshing, and cancelling an order need only the order ID, so there is no child address equivalent. Use the master wallet endpoints above for any order, including one created against a child address.The API also exposes a Find Fiat Deposit operation (POST /v1/wallets/{id}/deposit/fiat/finder) that locates a fiat deposit and its processing details from a payment reference. It is useful for reconciling a payment a customer says they sent against the order it belongs to.

Get Started

Wallets

Receive Payments

Send Payments

Convert & Manage

Compliance & Recovery

Integrations

Prerequisites

How It Works

Order Created

Account Issued

Payment Received

Settlement

Order Status

Collection Rails

Listing Master Wallet Payment Orders

Query Parameters

Response Example

Listing Child Address Payment Orders

Path Parameters

Query Parameters

Response Example

Response Fields

API Reference

Discovery & Configuration

Master Wallet

Child Address

​Prerequisites

​How It Works

Order Created

Account Issued

Payment Received

Settlement

​Order Status

​Collection Rails

​Listing Master Wallet Payment Orders

​Query Parameters

​Response Example

​Listing Child Address Payment Orders

​Path Parameters

​Query Parameters

​Response Example

​Response Fields

​API Reference

​Discovery & Configuration

​Master Wallet

​Child Address

Prerequisites

How It Works

Order Status

Collection Rails

Listing Master Wallet Payment Orders

Query Parameters

Response Example

Listing Child Address Payment Orders

Path Parameters

Query Parameters

Response Example

Response Fields

API Reference

Discovery & Configuration

Master Wallet

Child Address