> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesadepagos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cuentas virtuales

> Cuentas de cobro del partner y cuentas nominadas de sus clientes en API v2.

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`](/business-clients#crear-cliente).

## Cuenta del partner en Bolivia

```http theme={null}
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. |

```json theme={null}
{
  "country": "BO",
  "currency": "BOB",
  "label": "Cobros Bolivia",
  "externalReference": "cobros-bo"
}
```

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

```json theme={null}
{
  "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

```http theme={null}
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": [...] }`.

```json theme={null}
{
  "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

1. Crea el cliente con [`POST /v2/business-clients`](/business-clients#crear-cliente). Puedes elegir `settlementNetwork` (`Ethereum` o `Polygon`) y `settlementAsset` (`USDC` o `USDT`); los valores predeterminados son `Polygon` y `USDC`.
2. Completa su onboarding y solicita las verificaciones para las monedas en las que cobrará.
3. Obtén un enlace para cada sujeto con datos pendientes. Cuando se aprueban las verificaciones, la cuenta nominada se crea automáticamente.
4. 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

```http theme={null}
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:

```json theme={null}
{ "currencies": ["EUR", "USD"] }
```

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

```json theme={null}
{
  "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:

```http theme={null}
POST /v2/business-clients/{clientId}/endorsements/subjects/{subjectId}/link
```

```json theme={null}
{
  "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

```http theme={null}
PUT /v2/business-clients/{clientId}/withdrawal-address
```

```json theme={null}
{ "address": "0x2102d529741C5f6487d27a4792C4dC1f50913Bc8" }
```

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

```json theme={null}
{
  "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](/webhooks.md#deposit_virtual_account). 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](/webhooks.md#datos-del-pagador).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.