Cuentas virtuales - ON RAMP by Mesadepagos

Las cuentas virtuales permiten recibir pagos mediante las instrucciones de cobro devueltas por la API. Hay dos tipos: una cuenta del partner en Bolivia (BOB, pago por QR) y cuentas a nombre de un cliente en las monedas habilitadas por sus verificaciones. Todos los endpoints de esta página requieren un JWT Bearer.

Endpoints

Método	Ruta	Uso
`POST`	`/v2/virtual-accounts`	Crear una cuenta `BOB` del partner.
`GET`	`/v2/virtual-accounts`	Listar cuentas con filtros opcionales.
`GET`	`/v2/virtual-accounts/{id}`	Consultar una cuenta del partner por UUID.
`GET`	`/v2/business-clients/{clientId}/endorsements`	Consultar verificaciones del cliente.
`POST`	`/v2/business-clients/{clientId}/endorsements`	Solicitar verificaciones por moneda.
`POST`	`/v2/business-clients/{clientId}/endorsements/subjects/{subjectId}/link`	Emitir el enlace de un sujeto.
`PUT`	`/v2/business-clients/{clientId}/withdrawal-address`	Registrar o reemplazar la dirección de liquidación; solo Sandbox.
`GET`	`/v2/business-clients/{clientId}/withdrawal-address`	Consultar la dirección vigente; solo Sandbox.

clientId, subjectId e id deben ser UUID válidos. Para dar de alta un cliente, usa POST /v2/business-clients.

Cuenta del partner en Bolivia

POST /v2/virtual-accounts

Campo	Tipo	Requerido	Validación
`country`	`string`	Sí	Solo `BO`.
`currency`	`string`	No	Solo `BOB`; por defecto `BOB`.
`label`	`string`	No	Entre 1 y 150 caracteres después de quitar espacios exteriores.
`externalReference`	`string`	No	Entre 1 y 100 caracteres después de quitar espacios exteriores.

{
  "country": "BO",
  "currency": "BOB",
  "label": "Cobros Bolivia",
  "externalReference": "cobros-bo"
}

La respuesta 201 contiene una cuenta virtual con owner.type: "business" y paymentMethods: ["qr"]:

{
  "id": "b456c905-8d9a-4aff-9cf9-657e452e07c6",
  "owner": { "type": "business", "id": "4500678e-a900-4138-828c-b8f9c7ff5ebe" },
  "country": "BO",
  "currency": "BOB",
  "paymentMethods": ["qr"],
  "status": "active",
  "label": "Cobros Bolivia",
  "externalReference": "cobros-bo",
  "coordinates": {
    "holder": { "name": "Mi Comercio", "type": null, "address": null },
    "bank": {
      "name": "Administradora de tarjetas de crédito SA",
      "address": null
    },
    "accountNumber": "1234567890",
    "taxId": "1234567012"
  },
  "createdAt": "2026-09-23T14:49:35.054Z"
}

Solo se admite una cuenta del partner por país. Si ya existe, la API responde 409. Un cuerpo inválido responde 400. Las cuentas de clientes se generan a partir de verificaciones aprobadas; no se crean mediante este POST.

Listar y consultar cuentas

GET /v2/virtual-accounts?currency=EUR&clientId=550e8400-e29b-41d4-a716-446655440000

Query	Tipo	Comportamiento
`currency`	`string`	Código de tres letras, normalizado a mayúsculas. `BOB` devuelve cuentas del partner; otras monedas filtran cuentas nominadas de clientes.
`clientId`	`string`	UUID del cliente del partner; filtra sus cuentas nominadas.

Sin filtros, el listado devuelve solo cuentas nominadas de clientes, no la cuenta BOB del partner. Para incluir esta última, consulta ?currency=BOB. La combinación currency=BOB con clientId devuelve una lista vacía porque la cuenta BOB pertenece al partner. La respuesta siempre tiene la forma { "virtualAccounts": [...] }.

{
  "virtualAccounts": [
    {
      "id": "e74869b8-30d7-4abc-b5e1-9c905fd8f276",
      "owner": {
        "type": "businessClient",
        "id": "550e8400-e29b-41d4-a716-446655440000"
      },
      "country": "DE",
      "currency": "EUR",
      "paymentMethods": ["sepa"],
      "status": "ready",
      "label": null,
      "externalReference": null,
      "coordinates": {
        "holder": {
          "name": "Acme Bolivia SRL",
          "type": "business",
          "address": "Av. Central 123, Santa Cruz, BO"
        },
        "bank": { "name": "Banco Ejemplo", "address": null },
        "iban": "DE89370400440532013000"
      },
      "createdAt": "2026-09-23T14:49:35.054Z"
    }
  ]
}

GET /v2/virtual-accounts/{id} devuelve el mismo objeto, pero solo admite cuentas del partner. Si el UUID no corresponde a una cuenta del partner autenticado, responde 404. Para cuentas de clientes, usa el listado con clientId.

Campos de la cuenta

Campo	Tipo	Significado
`id`	`string`	UUID de la cuenta virtual.
`owner`	`object`	`type` es `business` o `businessClient`; `id` identifica al titular.
`country`	`string \| null`	País de la cuenta, si está disponible.
`currency`	`string`	Moneda de cobro.
`paymentMethods`	`string[]`	Rieles admitidos: `qr`, `ach`, `wire`, `swift`, `sepa`, `faster_payments`, `mena_local` o `aud_local`, según la cuenta.
`status`	`string`	`active`, `ready`, `provisioning` o `inactive`.
`label`, `externalReference`	`string \| null`	Valores definidos para la cuenta del partner; `null` para cuentas nominadas.
`coordinates`	`object \| null`	Instrucciones bancarias; puede ser `null` mientras se aprovisionan.
`createdAt`	`string`	Fecha ISO 8601.

En coordinates, holder incluye name, type y address; bank es opcional y contiene name y address. Según la moneda y el riel, pueden aparecer iban, accountNumber, swiftCode, taxId y routingNumbers (ach, wire, rtp). Comprueba status y la presencia de los datos requeridos antes de mostrar instrucciones de pago.

Cuentas nominadas de clientes

Crea el cliente con POST /v2/business-clients. Puedes elegir settlementNetwork (Ethereum o Polygon) y settlementAsset (USDC o USDT); los valores predeterminados son Polygon y USDC.
Completa su onboarding y solicita las verificaciones para las monedas en las que cobrará.
Obtén un enlace para cada sujeto con datos pendientes. Cuando se aprueban las verificaciones, la cuenta nominada se crea automáticamente.
Consulta GET /v2/virtual-accounts?clientId={clientId} para recuperar sus instrucciones de cobro. En Sandbox, registra la dirección de retiro para probar la liquidación.

Solicitar y consultar verificaciones

POST /v2/business-clients/{clientId}/endorsements

El cuerpo es opcional. Si se omite, se solicitan todas las monedas disponibles: EUR, USD, AED, AUD y GBP. Para acotar la solicitud, envía un arreglo no vacío:

{ "currencies": ["EUR", "USD"] }

La operación es idempotente y responde 200 con las verificaciones solicitadas y las monedas que no pudieron habilitarse:

{
  "endorsements": [
    {
      "currencies": ["EUR"],
      "status": "dataRequired",
      "requestedAt": "2026-09-23T12:00:00.000Z",
      "resolvedAt": null,
      "rejectionReason": null,
      "subjects": [
        {
          "id": "2363e78c-163b-4ff9-a25c-dfcc71d56c08",
          "name": "Acme Bolivia SRL",
          "type": "business",
          "isPrimary": true,
          "status": "pending",
          "pending": { "fields": ["address"], "documents": ["ID"] },
          "linkIssuedAt": null
        }
      ]
    }
  ],
  "failed": []
}

GET /v2/business-clients/{clientId}/endorsements devuelve directamente un arreglo de verificaciones con la misma estructura que endorsements. Los estados de verificación son pending, dataRequired, inProgress, inReview, approved y rejected; los del sujeto son pending, inReview, approved y rejected. requestedAt, resolvedAt, rejectionReason, name y linkIssuedAt pueden ser null. Cada subjects[].pending contiene arreglos fields y documents. Si failed contiene elementos, cada uno incluye currencies y reason: termsNotAccepted, verificationNotApproved, notAvailableForAccountType, alreadyRequested o unavailable. Esa moneda requiere revisar la causa; no avanza automáticamente.

Emitir el enlace de un sujeto

Usa el id del sujeto devuelto por el endpoint de verificaciones:

POST /v2/business-clients/{clientId}/endorsements/subjects/{subjectId}/link

{
  "url": "https://app.due.network/kyc_submissions/example?token=example",
  "issuedAt": "2026-09-23T12:00:00.000Z",
  "expiresAt": "2026-09-30T12:00:00.000Z"
}

El enlace vence a los siete días. Cada llamada emite uno nuevo. Las operaciones de verificaciones responden 404 cuando el cliente no existe o no pertenece al partner; el enlace también responde 404 si no existe el sujeto.

Dirección de retiro en Sandbox

PUT /v2/business-clients/{clientId}/withdrawal-address

{ "address": "0x2102d529741C5f6487d27a4792C4dC1f50913Bc8" }

La dirección debe ser EVM (0x seguido de 40 caracteres hexadecimales). PUT reemplaza la dirección activa y devuelve 200:

{
  "address": "0x2102d529741C5f6487d27a4792C4dC1f50913Bc8",
  "network": "Polygon",
  "registeredAt": "2026-09-23T15:10:10.365Z"
}

GET /v2/business-clients/{clientId}/withdrawal-address devuelve ese objeto o null si aún no hay dirección. Ambos endpoints están disponibles solo en Sandbox. La red devuelta corresponde a la elección hecha al crear el cliente. Comprueba la dirección antes de registrarla: la validación de formato no demuestra que el cliente la controle. Ambas rutas responden 404 si el cliente no existe o no pertenece al partner.

Notificaciones de cobro

Los cobros registrados por cuentas virtuales pueden generar una transacción con transactionType: "deposit_virtual_account". Sus cambios de estado se notifican mediante el webhook de transacciones. En details, amount es un string y currency indica la moneda fiat. details.payer aparece solo si existe un detalle de pagador registrado; consulta Datos del pagador.

​Endpoints

​Cuenta del partner en Bolivia

​Listar y consultar cuentas

​Campos de la cuenta

​Cuentas nominadas de clientes

​Solicitar y consultar verificaciones

​Emitir el enlace de un sujeto

​Dirección de retiro en Sandbox

​Notificaciones de cobro