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

# Payment Orders

> List and track payment orders for single-use virtual accounts, from creation through settlement

<Note>
  In a nutshell<br />
  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.
</Note>

## Prerequisites

Before using the Payment Orders API, ensure you have:

<Steps>
  <Step title="API Key">
    Get your API key from the [Blockradar Dashboard](https://dashboard.blockradar.co). Navigate to **Developers** to generate one.
  </Step>

  <Step title="Wallet Created">
    Create a wallet via the [Create Wallet API](/en/api-reference/wallets/create-wallet) or dashboard. You'll need the `walletId` for payment order operations.
  </Step>

  <Step title="Compliance Approved">
    Complete the Due Diligence process on the Dashboard: My wallets > Settings > Compliance
  </Step>

  <Step title="Feature Enabled">
    Request virtual accounts feature activation after compliance approval. Contact [support@blockradar.co](mailto:support@blockradar.co) or use live chat on the dashboard.
  </Step>

  <Step title="Mainnet Environment">
    Virtual accounts are only available on **MAINNET**. Testnet environments do not support virtual account operations.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

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

<CardGroup cols={2}>
  <Card title="Order Created" icon="plus">
    An order is generated with a reference, an expected amount, and its collection rail.
  </Card>

  <Card title="Account Issued" icon="building-columns">
    For the one-time virtual account rail, a single-use bank account is attached in `paymentInstructions`.
  </Card>

  <Card title="Payment Received" icon="credit-card">
    The customer pays the account before `expiresAt`; the order transitions to `processing` then `paid`.
  </Card>

  <Card title="Settlement" icon="wallet">
    The stablecoin equivalent is minted and settled to the linked wallet or child address.
  </Card>
</CardGroup>

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

```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
  }
}
```

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

```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
  }
}
```

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

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

***

## API Reference

### Discovery & Configuration

| Endpoint                                                                                                | Description                                                     |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [Get Supported Assets](/en/api-reference/deposit-fiat/get-supported-assets)                             | List the stablecoin assets available for fiat deposits          |
| [Get Supported Currencies](/en/api-reference/deposit-fiat/get-supported-currencies)                     | List the fiat currencies available for deposits                 |
| [Get Supported Rails](/en/api-reference/deposit-fiat/get-supported-rails)                               | List the supported fiat collection rails                        |
| [Resolve Payment Order Requirements](/en/api-reference/deposit-fiat/resolve-payment-order-requirements) | Resolve the fields required to create an order for a given rail |

### Master Wallet

| Endpoint                                                                                                | Description                                        |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [Master Wallet Get Quote](/en/api-reference/deposit-fiat/master-wallet-get-quote)                       | Get a quote before creating an order               |
| [Master Wallet Create Payment Order](/en/api-reference/deposit-fiat/master-wallet-create-payment-order) | Create a payment order for a master wallet         |
| [List Payment Orders](/en/api-reference/deposit-fiat/master-wallet-list-payment-orders)                 | List payment orders for a master wallet            |
| [Get Payment Order](/en/api-reference/deposit-fiat/master-wallet-get-payment-order)                     | Retrieve a single payment order by its identifier  |
| [Refresh Payment Order](/en/api-reference/deposit-fiat/master-wallet-refresh-payment-order)             | Refresh an order to get updated status and details |
| [Cancel Payment Order](/en/api-reference/deposit-fiat/master-wallet-cancel-payment-order)               | Cancel a pending payment order                     |

### Child Address

| Endpoint                                                                                                | Description                                |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| [Get Child Address Quote](/en/api-reference/deposit-fiat/child-address-get-quote)                       | Get a quote before creating an order       |
| [Create Child Address Payment Order](/en/api-reference/deposit-fiat/child-address-create-payment-order) | Create a payment order for a child address |
| [List Child Address Payment Orders](/en/api-reference/deposit-fiat/child-address-list-payment-orders)   | List payment orders for a child address    |

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