Órdenes de Pago

En resumen
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.

Requisitos previos

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

API Key

Obtén tu API key desde el Panel de Blockradar. Ve a Developers para generar una.

Wallet creada

Crea una wallet mediante la API Create Wallet o el panel. Necesitarás el walletId para las operaciones de órdenes de pago.

Cumplimiento aprobado

Completa el proceso de debida diligencia en el Panel: My wallets > Settings > Compliance

Función habilitada

Solicita la activación de la función de cuentas virtuales tras la aprobación de cumplimiento. Escribe a [email protected] o usa el chat en vivo del panel.

Entorno mainnet

Las cuentas virtuales solo están disponibles en MAINNET. Los entornos testnet no admiten operaciones con cuentas virtuales.

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.

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.

Orden creada

Se genera una orden con una referencia, un monto esperado y su vía de cobro.

Cuenta emitida

Para la vía de cuenta virtual de un solo uso, se adjunta una cuenta bancaria de un solo uso en paymentInstructions.

Pago recibido

El cliente paga la cuenta antes de expiresAt; la orden pasa a processing y luego a paid.

Liquidación

La stablecoin equivalente se emite y se liquida en la wallet o dirección secundaria vinculada.

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

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

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

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.

Referencia de API

Descubrimiento y configuración

Endpoint	Descripción
Get Supported Assets	Listar los activos stablecoin disponibles para depósitos en fiat
Get Supported Currencies	Listar las monedas fiat disponibles para depósitos
Get Supported Rails	Listar las vías de cobro en fiat admitidas
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	Obtener una cotización antes de crear una orden
Master Wallet Create Payment Order	Crear una orden de pago para una wallet maestra
List Payment Orders	Listar las órdenes de pago de una wallet maestra
Get Payment Order	Recuperar una única orden de pago por su identificador
Refresh Payment Order	Actualizar una orden para obtener el estado y los detalles más recientes
Cancel Payment Order	Cancelar una orden de pago pendiente

Dirección secundaria

Endpoint	Descripción
Get Child Address Quote	Obtener una cotización antes de crear una orden
Create Child Address Payment Order	Crear una orden de pago para una dirección secundaria
List Child Address Payment Orders	Listar las órdenes de pago de una dirección secundaria

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.

Comenzar

Billeteras

Recibir Pagos

Enviar Pagos

Convertir y Gestionar

Cumplimiento y Recuperación

Integraciones

Requisitos previos

Cómo funciona

Orden creada

Cuenta emitida

Pago recibido

Liquidación

Estado de la orden

Vías de cobro

Listar órdenes de pago de la wallet maestra

Parámetros de consulta

Ejemplo de respuesta

Listar órdenes de pago de la dirección secundaria

Parámetros de ruta

Parámetros de consulta

Ejemplo de respuesta

Campos de respuesta

Referencia de API

Descubrimiento y configuración

Wallet maestra

Dirección secundaria

​Requisitos previos

​Cómo funciona

Orden creada

Cuenta emitida

Pago recibido

Liquidación

​Estado de la orden

​Vías de cobro

​Listar órdenes de pago de la wallet maestra

​Parámetros de consulta

​Ejemplo de respuesta

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

​Parámetros de ruta

​Parámetros de consulta

​Ejemplo de respuesta

​Campos de respuesta

​Referencia de API

​Descubrimiento y configuración

​Wallet maestra

​Dirección secundaria

Requisitos previos

Cómo funciona

Estado de la orden

Vías de cobro

Listar órdenes de pago de la wallet maestra

Parámetros de consulta

Ejemplo de respuesta

Listar órdenes de pago de la dirección secundaria

Parámetros de ruta

Parámetros de consulta

Ejemplo de respuesta

Campos de respuesta

Referencia de API

Descubrimiento y configuración

Wallet maestra

Dirección secundaria