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

# Órdenes de Pago

> Liste y haga seguimiento de las órdenes de pago de cuentas virtuales de un solo uso, desde su creación hasta la liquidación

<Note>
  En resumen<br />
  Una orden de pago representa un único cobro de fiat esperado. Cuando utiliza la vía de **cuenta virtual de un solo uso**, cada orden está respaldada por una cuenta bancaria dedicada válida para un solo pago. Los endpoints de Órdenes de Pago le permiten listar y hacer seguimiento de cada orden a nivel de wallet maestra o acotadas a una dirección secundaria específica.
</Note>

## Requisitos previos

Antes de usar la API de Órdenes de Pago, asegúrate de tener:

<Steps>
  <Step title="API Key">
    Obtén tu API key desde el [Panel de Blockradar](https://dashboard.blockradar.co). Ve a **Developers** para generar una.
  </Step>

  <Step title="Wallet creada">
    Crea una wallet mediante la [API Create Wallet](/en/api-reference/wallets/create-wallet) o el panel. Necesitarás el `walletId` para las operaciones de órdenes de pago.
  </Step>

  <Step title="Cumplimiento aprobado">
    Completa el proceso de debida diligencia en el Panel: My wallets > Settings > Compliance
  </Step>

  <Step title="Función habilitada">
    Solicita la activación de la función de cuentas virtuales tras la aprobación de cumplimiento. Escribe a [support@blockradar.co](mailto:support@blockradar.co) o usa el chat en vivo del panel.
  </Step>

  <Step title="Entorno mainnet">
    Las cuentas virtuales solo están disponibles en **MAINNET**. Los entornos testnet no admiten operaciones con cuentas virtuales.
  </Step>

  <Step title="Soporte de stablecoin">
    Depositar fiat y convertirlo a una stablecoin es una función de pago. Asegúrate de que tu plan incluya acceso a stablecoins. Actualiza desde **Panel → Settings → Subscription**.
  </Step>
</Steps>

## Cómo funciona

Se crea una orden de pago cada vez que un cliente inicia un depósito en fiat. Para la vía `one_time_virtual_account`, Blockradar emite una nueva cuenta bancaria virtual vinculada a esa orden y a su conjunto de montos. Una vez que el cliente paga, la orden avanza por su ciclo de vida y la stablecoin correspondiente se emite y se liquida en la wallet o dirección vinculada.

<CardGroup cols={2}>
  <Card title="Orden creada" icon="plus">
    Se genera una orden con una referencia, un monto esperado y su vía de cobro.
  </Card>

  <Card title="Cuenta emitida" icon="building-columns">
    Para la vía de cuenta virtual de un solo uso, se adjunta una cuenta bancaria de un solo uso en `paymentInstructions`.
  </Card>

  <Card title="Pago recibido" icon="credit-card">
    El cliente paga la cuenta antes de `expiresAt`; la orden pasa a `processing` y luego a `paid`.
  </Card>

  <Card title="Liquidación" icon="wallet">
    La stablecoin equivalente se emite y se liquida en la wallet o dirección secundaria vinculada.
  </Card>
</CardGroup>

## Estado de la orden

Cada orden informa su estado actual dentro del ciclo de vida. Use el parámetro de consulta `status` para filtrar los resultados.

| Estado       | Descripción                                             |
| ------------ | ------------------------------------------------------- |
| `pending`    | Orden creada y a la espera del pago del cliente.        |
| `processing` | Pago recibido y en proceso de confirmación/liquidación. |
| `paid`       | Pago confirmado y liquidado correctamente.              |
| `expired`    | La orden no se pagó antes de `expiresAt`.               |
| `failed`     | El pago o la liquidación no se pudieron completar.      |
| `cancelled`  | La orden se canceló antes del pago.                     |

## Vías de cobro

El campo `rail` identifica cómo se cobra la orden. Las cuentas virtuales de un solo uso utilizan la vía `one_time_virtual_account`.

| Vía                        | Descripción                                            |
| -------------------------- | ------------------------------------------------------ |
| `one_time_virtual_account` | Una cuenta bancaria dedicada válida para un solo pago. |
| `payment_link`             | Un enlace de pago alojado.                             |
| `qr_code`                  | Un código QR escaneable.                               |

## Listar órdenes de pago de la wallet maestra

Devuelve una lista paginada de todas las órdenes de pago creadas bajo una wallet maestra. Use los parámetros de consulta para filtrar por estado, vía, moneda, activo, rango de fechas o búsqueda de texto libre.

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

### **Parámetros de consulta**

| Parámetro   | Tipo   | Descripción                                                                                        |
| ----------- | ------ | -------------------------------------------------------------------------------------------------- |
| `status`    | enum   | Filtrar por estado de la orden: `pending`, `paid`, `processing`, `expired`, `failed`, `cancelled`. |
| `rail`      | enum   | Filtrar por vía de cobro: `one_time_virtual_account`, `payment_link`, `qr_code`.                   |
| `currency`  | string | Código de moneda fiat ISO 4217 (3 caracteres), p. ej. `NGN`.                                       |
| `assetId`   | string | Identificador del activo stablecoin (UUID).                                                        |
| `search`    | string | Buscar por referencia, etiqueta, nombre de cuenta o número de cuenta.                              |
| `startDate` | string | Fecha de inicio ISO 8601 inclusiva. Obligatoria junto con `endDate`.                               |
| `endDate`   | string | Fecha de fin ISO 8601 inclusiva. Obligatoria junto con `startDate`.                                |
| `page`      | number | Número de página con base 1 (predeterminado: 1).                                                   |
| `limit`     | number | Registros por página (predeterminado: 10, rango: 1–100).                                           |

### **Ejemplo de respuesta**

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

## Listar órdenes de pago de la dirección secundaria

Devuelve las órdenes de pago acotadas a una única dirección secundaria. La respuesta incluye los mismos campos de la orden más detalles adicionales de liquidación, proveedor y cliente.

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

### **Parámetros de ruta**

| Parámetro   | Tipo   | Requerido | Descripción                                      |
| ----------- | ------ | --------- | ------------------------------------------------ |
| `walletId`  | string | Sí        | Identificador de la wallet (UUID).               |
| `addressId` | string | Sí        | Identificador de la dirección secundaria (UUID). |

### **Parámetros de consulta**

| Parámetro   | Tipo   | Descripción                                                                                        |
| ----------- | ------ | -------------------------------------------------------------------------------------------------- |
| `status`    | enum   | Filtrar por estado de la orden: `pending`, `paid`, `processing`, `expired`, `failed`, `cancelled`. |
| `rail`      | enum   | Filtrar por vía de cobro: `one_time_virtual_account`, `payment_link`, `qr_code`.                   |
| `currency`  | string | Código de moneda fiat ISO 4217 (3 caracteres), p. ej. `NGN`.                                       |
| `assetId`   | string | Identificador del activo stablecoin (UUID).                                                        |
| `search`    | string | Buscar por referencia, etiqueta, nombre de cuenta o número de cuenta.                              |
| `startDate` | string | Fecha de inicio ISO 8601 inclusiva. Obligatoria junto con `endDate`.                               |
| `endDate`   | string | Fecha de fin ISO 8601 inclusiva. Obligatoria junto con `startDate`.                                |

### **Ejemplo de respuesta**

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

## Campos de respuesta

| Campo                 | Descripción                                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `id`                  | Identificador único de la orden de pago.                                                                   |
| `type`                | Tipo de orden. `deposit` para cobros en fiat.                                                              |
| `rail`                | Vía de cobro utilizada para la orden.                                                                      |
| `reference`           | Su referencia para la orden.                                                                               |
| `status`              | Estado actual de la orden dentro del ciclo de vida.                                                        |
| `currency`            | Moneda fiat ISO 4217 del pago esperado.                                                                    |
| `amount`              | Monto de stablecoin a emitir.                                                                              |
| `amountFiat`          | Valor en fiat de la orden antes de comisiones.                                                             |
| `feeFiat`             | Comisión cobrada en fiat.                                                                                  |
| `amountFiatPayable`   | Monto total en fiat que el cliente debe pagar (`amountFiat` + `feeFiat`).                                  |
| `expiresAt`           | Marca de tiempo tras la cual una orden no pagada expira.                                                   |
| `paymentInstructions` | Cómo paga el cliente. Contiene los datos del `bank` de un solo uso para la vía `one_time_virtual_account`. |
| `asset`               | El activo stablecoin en el que se liquida la orden.                                                        |
| `wallet`              | La wallet maestra a la que pertenece la orden.                                                             |
| `meta`                | Metadatos de paginación del conjunto de resultados.                                                        |
| `analytics`           | Recuentos agregados de órdenes por estado.                                                                 |

<Note>
  Los campos `amountFiatReceived`, `amountSettled`, `providerReference`, `provider` y `customer` se devuelven en el endpoint de dirección secundaria y se completan a medida que la orden avanza por la liquidación.
</Note>

***

## Referencia de API

### Descubrimiento y configuración

| Endpoint                                                                                                | Descripción                                                                |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Get Supported Assets](/en/api-reference/deposit-fiat/get-supported-assets)                             | Listar los activos stablecoin disponibles para depósitos en fiat           |
| [Get Supported Currencies](/en/api-reference/deposit-fiat/get-supported-currencies)                     | Listar las monedas fiat disponibles para depósitos                         |
| [Get Supported Rails](/en/api-reference/deposit-fiat/get-supported-rails)                               | Listar las vías de cobro en fiat admitidas                                 |
| [Resolve Payment Order Requirements](/en/api-reference/deposit-fiat/resolve-payment-order-requirements) | Resolver los campos requeridos para crear una orden en una vía determinada |

### Wallet maestra

| Endpoint                                                                                                | Descripción                                                              |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [Master Wallet Get Quote](/en/api-reference/deposit-fiat/master-wallet-get-quote)                       | Obtener una cotización antes de crear una orden                          |
| [Master Wallet Create Payment Order](/en/api-reference/deposit-fiat/master-wallet-create-payment-order) | Crear una orden de pago para una wallet maestra                          |
| [List Payment Orders](/en/api-reference/deposit-fiat/master-wallet-list-payment-orders)                 | Listar las órdenes de pago de una wallet maestra                         |
| [Get Payment Order](/en/api-reference/deposit-fiat/master-wallet-get-payment-order)                     | Recuperar una única orden de pago por su identificador                   |
| [Refresh Payment Order](/en/api-reference/deposit-fiat/master-wallet-refresh-payment-order)             | Actualizar una orden para obtener el estado y los detalles más recientes |
| [Cancel Payment Order](/en/api-reference/deposit-fiat/master-wallet-cancel-payment-order)               | Cancelar una orden de pago pendiente                                     |

### Dirección secundaria

| Endpoint                                                                                                | Descripción                                            |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [Get Child Address Quote](/en/api-reference/deposit-fiat/child-address-get-quote)                       | Obtener una cotización antes de crear una orden        |
| [Create Child Address Payment Order](/en/api-reference/deposit-fiat/child-address-create-payment-order) | Crear una orden de pago para una dirección secundaria  |
| [List Child Address Payment Orders](/en/api-reference/deposit-fiat/child-address-list-payment-orders)   | Listar las órdenes de pago de una dirección secundaria |

<Note>
  Recuperar, actualizar y cancelar una orden solo requieren el ID de la orden, por
  lo que no existe un equivalente para direcciones secundarias. Usa los endpoints
  de la wallet maestra anteriores para cualquier orden, incluidas las creadas
  contra una dirección secundaria.

  La API también expone una operación **Find Fiat Deposit**
  (`POST /v1/wallets/{id}/deposit/fiat/finder`) que localiza un depósito en fiat y
  sus detalles de procesamiento a partir de una referencia de pago. Es útil para
  conciliar un pago que un cliente afirma haber enviado con la orden a la que
  pertenece.
</Note>