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

CurrencyRailCountriesExtra required fields
BRLPIXBrazil—
MXNBASE / MXNSPEIMexico—
USDBASEACH / WireUnited States—
EURBASE / EURDESEPAEurope / Germany—
MXNUSDSPEI (USD-settled)Mexico—
ARSCVU/CBUArgentinadocument_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.
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'

​
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.
​
accounts
array
required
Array of account creation objects.
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
​
account_id
string
required
The virtual account ID.
​
action
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"
  }'

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