Virtual Accounts

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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. KYC approval (is_va_approved: true) is required before a virtual account can be issued.

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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "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 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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. All customers must have is_va_approved: true 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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN'

KYC Requirement

Before issuing a virtual account, the customer’s KYC must be approved. Check the is_va_approved flag on the customer object:

curl -X GET 'https://api.yativo.com/api/v1/customer/da44a3e6-eb5d-429f-8d17-357aa5a6cdf2' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

If is_va_approved is false, submit KYC first. See the Customers & KYC guide.

Deposits (Payins)Virtual Cards

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

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