Virtual accounts - ON RAMP by Mesadepagos

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.

Partner account in Bolivia

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.

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

The 201 response is a virtual account with owner.type: "business" and 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": "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

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": [...] }.

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

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

Request and retrieve endorsements

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:

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

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

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

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

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

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

{ "address": "0x2102d529741C5f6487d27a4792C4dC1f50913Bc8" }

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

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

​Endpoints

​Partner account in Bolivia

​List and retrieve accounts

​Account fields

​Named client accounts

​Request and retrieve endorsements

​Issue a subject link

​Withdrawal address in Sandbox

​Collection notifications