Skip to main content
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

CurrencyRailCountries
BRLPIXBrazil
MXNBASE / MXNSPEIMexico
USDBASEACH / WireUnited States
EURBASE / EURDESEPAEurope / Germany
MXNUSDSPEI (USD-settled)Mexico
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
​
customer_id
string
required
The ID of the KYC-approved customer to issue the account to.
​
currency
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"
  }'

{
  "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
​
currency
string
Filter by currency code (e.g. BRL, USD).
​
status
string
Filter by account status.
​
start_date
string
From date (ISO 8601).
​
q
string
Search query — account number, customer name, etc.
​
per_page
number
Results per page.
​
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}
​
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}
​
account_number
string
required
The account number (not the account ID).
​
customer_id
string
Filter by customer ID.
​
status
string
Filter by payment status.
​
start_date
string
From date (ISO 8601).
​
end_date
string
To date (ISO 8601).
​
page
number
Page number.
​
per_page
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}
​
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'

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