Ó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 desde el panel (consulta Crear una Billetera Principal). 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.

Flujo de creación vinculado a una sesión

Inicie la creación de la orden de pago solicitando una cotización con assetId, currency, amount y rail. Cuando el depósito pertenezca a un cliente existente, incluya también customerId para que se pueda reutilizar el KYC del proveedor ya guardado. El adaptador del proveedor infiere el corredor de KYC a partir de la moneda fiat seleccionada. La cotización devuelve un sessionId y sessionExpiresAt. La sesión vincula la wallet, el activo de la wallet, la moneda fiat, el monto, la vía, el proveedor, la ruta de conversión, el cliente y el corredor de KYC durante 20 minutos. Recomendamos usar el sessionId devuelto en cada solicitud posterior:

Inicialice el formulario con additionalDataRequirements.data cuando no sea null. Contiene los valores reutilizables ya guardados para el cliente, el proveedor y el corredor.
Recopile los valores faltantes que exija additionalDataRequirements.schema.
Si el esquema contiene un x-resolution, llame a POST /v1/wallets/{id}/deposit/fiat/payment-order-requirements/resolve con sessionId y el additionalData actual.
Combine los valores resueltos en additionalData.
Cree la orden con sessionId, additionalData y cualquier campo opcional de la orden, como reference o 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
  }
}

Por brevedad, arriba solo se muestran los campos de nivel superior del esquema; renderice el JSON Schema completo y específico del proveedor que devuelve la 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"
}

El ejemplo anterior corresponde a un perfil de persona de Paycrest para NGN: idDocument.number es el NIN de 11 dígitos del cliente y taxId.value es su BVN de 11 dígitos. Los requisitos varían según el proveedor, el corredor y el tipo de entidad, por lo que siempre debe renderizar el esquema que devuelve la cotización en lugar de codificar estos campos de forma fija. Cuando la orden se crea con KYC en línea, Blockradar lo guarda asociado al cliente del negocio, al proveedor seleccionado y al corredor. Una cotización posterior con el mismo customerId y corredor devuelve el KYC guardado en additionalDataRequirements.data. Enviar un KYC modificado en una orden posterior actualiza el perfil guardado del corredor; no se necesita un endpoint de KYC independiente.

No reutilice una sesión con valores de activo, moneda, monto, vía o proveedor de otra cotización. Si la API devuelve FIAT_DEPOSIT_SESSION_EXPIRED, FIAT_DEPOSIT_SESSION_MISMATCH o FIAT_DEPOSIT_SESSION_UNAVAILABLE, solicite una nueva cotización y reinicie la resolución de requisitos.

Por compatibilidad con versiones anteriores, sessionId es opcional. Si lo omite, envíe los valores originales de assetId, currency, amount y rail en las solicitudes de resolución de requisitos y de creación de la orden. Cuando sessionId está presente, los valores almacenados en la sesión son los que prevalecen.

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

Flujo de creación vinculado a una sesión

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

​Flujo de creación vinculado a una sesión

​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

Flujo de creación vinculado a una sesión

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