Skip to main content
Virtual accounts give each customer a unique receiving account number. When a payment arrives, it’s automatically matched and credited to the right customer. KYC must be approved before a virtual account can be issued.
Each customer can hold one virtual account per currency. KYC approval (is_va_approved: true) is required before creating virtual accounts.
interface VirtualAccount {
  account_id: string;
  account_number: string;
  account_type: string;
  currency: string;
  customer_id: string;
  created_at: string;
}

interface CreateVirtualAccountRequest {
  customer_id: string;    // must be KYC-approved
  currency: SupportedCurrency;
}

type SupportedCurrency =
  | "USDBASE"   // USD (standard)
  | "EURBASE"   // EUR (standard)
  | "EURDE"     // EUR (Germany)
  | "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. Supported values: USDBASE, EURBASE, EURDE, MXN, MXNBASE, MXNUSD, BRL. For enterprise currencies, contact your integration team.
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": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
    "currency": "USDBASE"
  }'

{
  "status": "success",
  "status_code": 201,
  "message": "Virtual account creation in progress",
  "data": {
    "account_id": "va_xxxxxx",
    "account_number": "9900123456",
    "account_type": "savings",
    "currency": "USDBASE",
    "created_at": "2026-03-26T10:00:00Z"
  }
}

​
List virtual accounts

GET /business/virtual-account

curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Get virtual account

GET /business/virtual-account/show/{virtual_account_id}
​
virtual_account_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'

​
Delete virtual account

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

curl -X DELETE 'https://api.yativo.com/api/v1/business/virtual-account/delete-virtual-account/va_xxxxxx' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Virtual account transaction history

Retrieve payment history for a specific virtual account number. 
POST /business/virtual-account/history/{account_number}
​
account_number
string
required
The account number (not the account 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-03-01&end_date=2026-03-31' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "status": "success",
  "status_code": 200,
  "message": "Records retrieved successfully",
  "data": [
    {
      "amount": 1000,
      "currency": "USD",
      "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 }
}