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

# Virtual accounts

> Partner collection accounts and named client accounts in API v2.

Virtual accounts let you receive payments using the collection instructions returned by the API. There are two types: a **partner** account in Bolivia (`BOB`, QR payments) and **client named** accounts in currencies enabled by their endorsements. Every endpoint on this page requires a Bearer JWT.

## Endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/v2/virtual-accounts` | Create a partner `BOB` account. |
| `GET` | `/v2/virtual-accounts` | List accounts with optional filters. |
| `GET` | `/v2/virtual-accounts/{id}` | Retrieve a partner account by UUID. |
| `GET` | `/v2/business-clients/{clientId}/endorsements` | Retrieve client endorsements. |
| `POST` | `/v2/business-clients/{clientId}/endorsements` | Request endorsements by currency. |
| `POST` | `/v2/business-clients/{clientId}/endorsements/subjects/{subjectId}/link` | Issue a subject link. |
| `PUT` | `/v2/business-clients/{clientId}/withdrawal-address` | Register or replace a settlement address; Sandbox only. |
| `GET` | `/v2/business-clients/{clientId}/withdrawal-address` | Retrieve the current address; Sandbox only. |

`clientId`, `subjectId`, and `id` must be valid UUIDs. To create a client, use [`POST /v2/business-clients`](/en/business-clients#create-a-client).

## Partner account in Bolivia

```http theme={null}
POST /v2/virtual-accounts
```

| Field | Type | Required | Validation |
| - | - | - | - |
| `country` | `string` | Yes | Only `BO`. |
| `currency` | `string` | No | Only `BOB`; defaults to `BOB`. |
| `label` | `string` | No | 1 to 150 characters after trimming outer spaces. |
| `externalReference` | `string` | No | 1 to 100 characters after trimming outer spaces. |

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

The `201` response is a virtual account with `owner.type: "business"` and `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": "Bolivia collections",
  "externalReference": "collections-bo",
  "coordinates": {
    "holder": { "name": "My Business", "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"
}
```

Only one partner account per country is allowed. If one already exists, the API returns `409`. Invalid input returns `400`. Client accounts are created after endorsement approval, not through this `POST`.

## List and retrieve accounts

```http theme={null}
GET /v2/virtual-accounts?currency=EUR&clientId=550e8400-e29b-41d4-a716-446655440000
```

| Query | Type | Behavior |
| - | - | - |
| `currency` | `string` | Three letter code, converted to uppercase. `BOB` returns partner accounts; other currencies filter named client accounts. |
| `clientId` | `string` | Partner client UUID; filters named accounts owned by that client. |

With no filters, the list returns **named client accounts only**; it excludes the partner's `BOB` account. Use `?currency=BOB` to retrieve that account. Combining `currency=BOB` with `clientId` returns an empty list because the `BOB` account belongs to the partner. The response is always shaped as `{ "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": "Example Bank", "address": null },
        "iban": "DE89370400440532013000"
      },
      "createdAt": "2026-09-23T14:49:35.054Z"
    }
  ]
}
```

`GET /v2/virtual-accounts/{id}` returns the same object, but **only supports partner accounts**. It returns `404` if the UUID does not identify an account of the authenticated partner. Use the list with `clientId` for client accounts.

### Account fields

| Field | Type | Meaning |
| - | - | - |
| `id` | `string` | Virtual account UUID. |
| `owner` | `object` | `type` is `business` or `businessClient`; `id` identifies the owner. |
| `country` | `string \| null` | Account country, when available. |
| `currency` | `string` | Collection currency. |
| `paymentMethods` | `string[]` | Supported rails: `qr`, `ach`, `wire`, `swift`, `sepa`, `faster_payments`, `mena_local`, or `aud_local`, depending on the account. |
| `status` | `string` | `active`, `ready`, `provisioning`, or `inactive`. |
| `label`, `externalReference` | `string \| null` | Partner account values; `null` for named client accounts. |
| `coordinates` | `object \| null` | Bank instructions; may be `null` during provisioning. |
| `createdAt` | `string` | ISO 8601 timestamp. |

Within `coordinates`, `holder` has `name`, `type`, and `address`. The optional `bank` object has `name` and `address`. Depending on the currency and rail, `iban`, `accountNumber`, `swiftCode`, `taxId`, and `routingNumbers` (`ach`, `wire`, `rtp`) may be present. Check `status` and the required fields before displaying payment instructions.

## Named client accounts

1. Create the client with [`POST /v2/business-clients`](/en/business-clients#create-a-client). You may choose `settlementNetwork` (`Ethereum` or `Polygon`) and `settlementAsset` (`USDC` or `USDT`); the defaults are `Polygon` and `USDC`.
2. Complete onboarding and request endorsements for the currencies the client needs.
3. Issue a link for each subject with pending requirements. Once the endorsements are approved, the named account is created automatically.
4. Query `GET /v2/virtual-accounts?clientId={clientId}` for payment instructions. In Sandbox, register a withdrawal address to test settlement.

### Request and retrieve endorsements

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

The body is optional. Omitting it requests all available currencies: `EUR`, `USD`, `AED`, `AUD`, and `GBP`. To narrow the request, send a nonempty array:

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

The operation is idempotent and returns `200` with requested endorsements and currencies that could not be enabled:

```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` returns an **array of endorsements** with the same structure as `endorsements`. Endorsement statuses are `pending`, `dataRequired`, `inProgress`, `inReview`, `approved`, and `rejected`; subject statuses are `pending`, `inReview`, `approved`, and `rejected`. `requestedAt`, `resolvedAt`, `rejectionReason`, `name`, and `linkIssuedAt` may be `null`. Each `subjects[].pending` contains `fields` and `documents` arrays.

Each item in `failed` has `currencies` and a `reason`: `termsNotAccepted`, `verificationNotApproved`, `notAvailableForAccountType`, `alreadyRequested`, or `unavailable`. Review the reason because that currency will not proceed automatically.

### Issue a subject link

Use the subject `id` returned by the endorsements endpoint:

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

Links expire after seven days. Each call issues a new link. Endorsement operations return `404` if the client does not exist or does not belong to the partner; the link operation also returns `404` when the subject is missing.

### Withdrawal address in Sandbox

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

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

The address must be EVM formatted (`0x` followed by 40 hexadecimal characters). `PUT` replaces the active address and returns `200`:

```json theme={null}
{
  "address": "0x2102d529741C5f6487d27a4792C4dC1f50913Bc8",
  "network": "Polygon",
  "registeredAt": "2026-09-23T15:10:10.365Z"
}
```

`GET /v2/business-clients/{clientId}/withdrawal-address` returns this object or `null` if there is no address yet. Both endpoints are available **in Sandbox only**. The returned network matches the network selected when creating the client. Check the address before registering it: format validation does not prove the client controls it.

Both routes return `404` if the client does not exist or does not belong to the partner.

## Collection notifications

Collections recorded through virtual accounts may create a transaction with `transactionType: "deposit_virtual_account"`. Status changes are sent through the [transaction webhook](/en/webhooks.md#deposit_virtual_account). In `details`, `amount` is a `string` and `currency` is the fiat currency. `details.payer` appears only when a payer detail is recorded; see [Payer details](/en/webhooks.md#payer-details).


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