Virtual Account

Overview

Virtual Accounts allow clients to create multiple sub-accounts linked to a single bank account, providing enhanced transaction organization and control. Instead of being limited to one bank account for all operations, clients can create as many virtual accounts as needed, each with its own balance and transaction history.

Key Features

• Multiple Accounts: Create unlimited virtual accounts linked to your bank account
• Individual Balances: Each virtual account maintains its own separate balance
• Full Transaction Support: Execute all transaction flows (PIX, bank transfers, etc.) using virtual accounts
• Enhanced Control: Better organization and tracking of transactions by purpose or category
• Unique Identifiers: Each virtual account has a unique identifier for easy reference

How It Works

Bank Account Relationship

• Every virtual account must be linked to an existing bank account
• Multiple virtual accounts can share the same underlying bank account
• Virtual accounts inherit the banking details from their linked bank account

Transaction Flow

• Transactions can be executed directly from virtual accounts
• When using a virtual account for transactions, specify virtualAccountId instead of bankAccountId
• All PIX transactions support virtual accounts as the source
• Transaction history is maintained at the virtual account level

Balance Management

• Each virtual account maintains its own independent balance
• Balances include: available, blocked, total, pending debits, and pending credits
• Virtual account balances are separate from the main bank account balance

API Endpoints

List Virtual Accounts

GET /banking/api/virtualAccounts

Retrieve all virtual accounts for your company.

Get Virtual Account

GET /banking/api/virtualAccounts/{virtualAccountId}

Get details of a specific virtual account.

Get Virtual Account Balance

GET /banking/api/virtualAccounts/{virtualAccountId}/balance

Retrieve the current balance information for a virtual account.

Virtual Account Structure

{
  "id": "47904546-210c-4097-ab0c-195d339f84bf",
  "bankAccountId": "e29b550e-41d4-4a71-b840-446655440111",
  "companyId": "123e4567-e89b-12d3-a456-426614174002",
  "name": "Main Virtual Account",
  "accountIdentifier": "VA001",
  "bankingDetails": {
    "accountHolder": {
      "legalName": "Trace Finance Ltd",
      "taxId": "12345678901",
      "address": {
        "country": "BR",
        "address": "Rua Example, 123, São Paulo, SP"
      }
    },
    "currency": "BRL",
    "accountNumber": "123456-7",
    "branchCode": "1584",
    "bank": {
      "name": "Banco do Brasil",
      "ispbCode": "00000000",
      "bankCode": "001"
    }
  },
  "createdAt": "2024-05-22T14:00:00Z",
  "updatedAt": "2024-05-22T14:00:00Z"
}

Using Virtual Accounts in Transactions

When creating PIX transactions, specify the virtual account instead of the bank account:

{
  "virtualAccountId": "47904546-210c-4097-ab0c-195d339f84bf",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "destination": {
    // destination details
  },
  "idempotentId": "unique-transaction-id"
}

Note: virtualAccountId and bankAccountId are mutually exclusive - provide exactly one in transaction requests.

Technical Details

Account Identifier Generation

Virtual accounts receive a unique accountIdentifier that is automatically generated using a base-encoded incremental system. This identifier provides a human-readable reference for the virtual account.

Banking Details

Virtual accounts inherit their banking details from the linked bank account, including:

• Account holder information
• Bank details (name, ISPB code, bank code)
• Account number and branch code
• Currency

Management

• Virtual accounts are created through TraceFinance's backoffice system
• Virtual accounts cannot be deleted or deactivated once created
• All virtual accounts are permanent and maintain their transaction history

Please feel free to contact our support team if you need help with virtual account creation or management.