Virtual Accounts

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "BRL"
  }'

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "MXNBASE"
  }'

const { data } = await client.post('/business/virtual-account/create', {
  customer_id: customerId,
  currency: 'BRL',
}, {
  headers: { 'Idempotency-Key': crypto.randomUUID() },
});
console.log('Account number:', data.data.account_number);

{
  "status": "success",
  "status_code": 201,
  "message": "Virtual account creation in progress",
  "data": {
    "account_id": "va_xxxxxx",
    "account_number": "9900123456",
    "account_type": "savings",
    "currency": "BRL",
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "created_at": "2026-04-01T10:00:00Z"
  }
}

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "BRL"
  }'

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "MXNBASE"
  }'

const { data } = await client.post('/business/virtual-account/create', {
  customer_id: customerId,
  currency: 'BRL',
}, {
  headers: { 'Idempotency-Key': crypto.randomUUID() },
});
console.log('Account number:', data.data.account_number);

{
  "status": "success",
  "status_code": 201,
  "message": "Virtual account creation in progress",
  "data": {
    "account_id": "va_xxxxxx",
    "account_number": "9900123456",
    "account_type": "savings",
    "currency": "BRL",
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "created_at": "2026-04-01T10:00:00Z"
  }
}

Virtual accounts give each customer a unique local bank account number. When a payment arrives at that number, it is automatically matched and credited to the right customer — no manual reconciliation needed.

Each customer can hold one virtual account per currency. The customer needs an approved endorsement for that currency before you can issue the account. See KYC Requirement.

Supported Rails

Currency	Rail	Countries	Extra required fields
`BRL`	PIX	Brazil	—
`MXNBASE` / `MXN`	SPEI	Mexico	—
`USDBASE`	ACH / Wire	United States	—
`EURBASE` / `EURDE`	SEPA	Europe / Germany	—
`MXNUSD`	SPEI (USD-settled)	Mexico	—
`ARS`	CVU/CBU	Argentina	`document_id`, `document_type`

Argentina accounts require the customer’s document_id and document_type ("CUIT", "CUIL", or "CDI") in the create request. The customer must be an Argentine resident. See the Regional Payouts guide for details.

Type Definitions

interface VirtualAccount {
  account_id: string;
  account_number: string;
  account_type: string;
  currency: string;
  customer_id: string;
  created_at: string;
}

type SupportedCurrency =
  | "USDBASE"   // USD (standard ACH/wire)
  | "EURBASE"   // EUR (SEPA standard)
  | "EURDE"     // EUR (Germany SEPA)
  | "MXN"       // Mexican Peso via SPEI
  | "MXNBASE"   // Mexican Peso via SPEI
  | "MXNUSD"   // USD-settled via SPEI
  | "BRL";      // Brazilian Real via PIX

Create Virtual Account

POST /business/virtual-account/create

string

required

The ID of the KYC-approved customer to issue the account to.

string

required

Currency for the virtual account (see supported values above).

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "BRL"
  }'

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "MXNBASE"
  }'

const { data } = await client.post('/business/virtual-account/create', {
  customer_id: customerId,
  currency: 'BRL',
}, {
  headers: { 'Idempotency-Key': crypto.randomUUID() },
});
console.log('Account number:', data.data.account_number);

{
  "status": "success",
  "status_code": 201,
  "message": "Virtual account creation in progress",
  "data": {
    "account_id": "va_xxxxxx",
    "account_number": "9900123456",
    "account_type": "savings",
    "currency": "BRL",
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "created_at": "2026-04-01T10:00:00Z"
  }
}

List Virtual Accounts

GET /business/virtual-account

string

Filter by currency code (e.g. BRL, USD).

string

Filter by account status.

string

From date (ISO 8601).

string

Search query — account number, customer name, etc.

number

Results per page.

number

Page number.

curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account?currency=BRL&per_page=20' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

Get Virtual Account

GET /business/virtual-account/show/{id}

string

required

The virtual account ID.

curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account/show/va_xxxxxx' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

Virtual Account Transaction History

Retrieve all payments received into a specific virtual account:

POST /business/virtual-account/history/{account_number}

string

required

The account number (not the account ID).

string

Filter by customer ID.

string

Filter by payment status.

string

From date (ISO 8601).

string

To date (ISO 8601).

number

Page number.

number

Results per page.

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/history/9900123456?start_date=2026-04-01&end_date=2026-04-30' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "data": [
    {
      "amount": 1000,
      "currency": "BRL",
      "status": "completed",
      "credited_amount": 950,
      "transaction_id": "TXNMP2HK81BHJ",
      "sender_name": "John Smith",
      "account_number": "9900123456",
      "transaction_fees": 50
    }
  ],
  "pagination": { "total": 12, "per_page": 20, "current_page": 1 }
}

Delete Virtual Account

DELETE /business/virtual-account/delete-virtual-account/{id}

string

required

The virtual account ID to delete.

curl -X DELETE 'https://api.yativo.com/api/v1/business/virtual-account/delete-virtual-account/va_xxxxxx' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

The account stops accepting funds and you receive a virtual_account.deleted webhook. An ID that doesn’t exist or isn’t yours returns 404.

Bulk Account Creation

Create virtual accounts for multiple customers in a single request. Useful when onboarding a batch of pre-verified customers.

POST https://api.yativo.com/api/v1/business/virtual-account/bulk-account-creation

Requires Idempotency-Key header. Every customer needs an approved endorsement for the currency before bulk creation.

array

required

Array of account creation objects.

Show accounts item fields

string

required

The KYC-approved customer UUID.

string

required

Currency for the virtual account (e.g. "BRL", "MXNBASE", "USDBASE").

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/bulk-account-creation' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: bulk-va-june-001' \
  -d '{
    "accounts": [
      { "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2", "currency": "BRL" },
      { "customer_id": "c586066b-0f29-468f-b775-15483871a202", "currency": "BRL" },
      { "customer_id": "f7e8d9c0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", "currency": "MXNBASE" }
    ]
  }'

Enable / Disable Virtual Account

Suspend or reactivate a virtual account without deleting it. Suspended accounts stop receiving deposits.

PUT https://api.yativo.com/api/v1/business/virtual-account/enable_disable_virtual_account

string

required

The virtual account ID.

string

required

"enable" or "disable".

curl -X PUT 'https://api.yativo.com/api/v1/business/virtual-account/enable_disable_virtual_account' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: disable-va-001' \
  -d '{
    "account_id": "va_xxxxxx",
    "action": "disable"
  }'

curl -X PUT 'https://api.yativo.com/api/v1/business/virtual-account/enable_disable_virtual_account' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: enable-va-001' \
  -d '{
    "account_id": "va_xxxxxx",
    "action": "enable"
  }'

Refund a Payin

Reverse a specific incoming deposit back to the sender. Use this when a customer payment needs to be returned.

POST https://api.yativo.com/api/v1/business/virtual-account/refundPayin/{externalId}

string

required

The external transaction ID of the deposit to refund. This is returned in the virtual_account.deposit webhook payload.

Requires Idempotency-Key header. Refunds are subject to the availability of the underlying payment rail — not all currencies support reversals.

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/refundPayin/TXNMP2HK81BHJ' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: refund-TXNMP2HK81BHJ-001'

List All Virtual Account History

Retrieve transaction history across all virtual accounts (not scoped to a specific account number):

GET https://api.yativo.com/api/v1/business/virtual-account/histories

Get Customer Virtual Accounts

List all virtual accounts belonging to a specific customer:

GET https://api.yativo.com/api/v1/business/virtual-account/customer/accounts/{customerId}

string

required

The customer UUID.

curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account/customer/accounts/da44a3e6-eb5d-429f-8d17-357aa5a6cdf2' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

KYC Requirement

Each currency needs a specific endorsement. Find it with:

curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account/currencies-and-endorsements' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

Then check that the customer’s endorsement for it is approved, either from the endorsement.updated webhook or from the endorsement list on GET /customer/{customer_id}. If it isn’t, submit or fix KYC first. See Track verification with endorsements.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

SDKs

Regional Guides

Virtual Accounts

Supported Rails

Create Virtual Account

List Virtual Accounts

Get Virtual Account

Virtual Account Transaction History

Delete Virtual Account

Bulk Account Creation

Enable / Disable Virtual Account

Refund a Payin

List All Virtual Account History

Get Customer Virtual Accounts

KYC Requirement

​Supported Rails

​Create Virtual Account

​List Virtual Accounts

​Get Virtual Account

​Virtual Account Transaction History

​Delete Virtual Account

​Bulk Account Creation

​Enable / Disable Virtual Account

​Refund a Payin

​List All Virtual Account History

​Get Customer Virtual Accounts

​KYC Requirement

Supported Rails

Create Virtual Account

List Virtual Accounts

Get Virtual Account

Virtual Account Transaction History

Delete Virtual Account

Bulk Account Creation

Enable / Disable Virtual Account

Refund a Payin

List All Virtual Account History

Get Customer Virtual Accounts

KYC Requirement