Overview
A virtual account is a fiat account issued directly by Trace Finance. It suits customers who run their own treasury, intercompany flows, or proprietary commerce on Trace Finance. UseVIRTUAL as the account type. Every account is multi-currency, so crypto support is always included alongside the fiat assets you enable.
Verification for a virtual account follows Trace Finance’s compliance baseline only, which is a lighter document set than a named account. Additional documents apply only when the owner is itself a regulated payment entity, such as a payment service provider, a banking-as-a-service provider, or a virtual-asset service provider. The exact set for your account is always returned in requirements.currentlyDue when you create it. See BRL virtual accounts for the full checklist.
Prerequisites
- Valid authentication credentials.
- Account owner details: legal name (or first and last name for an individual), tax ID, industry, expected monthly volume, and address.
- The baseline document checklist. See BRL virtual accounts. The documents that apply to your account appear in
requirements.currentlyDueafter creation.
Steps
1
Create the account
Submit a request with the fiat assets to enable and the account owner’s details. Set each fiat asset’s The response returns the account in
accountType to VIRTUAL. Crypto support is always included, so you don’t declare it or set its accountType.ACTION_REQUIRED status, with the document types required for onboarding listed under requirements.currentlyDue. For an individual owner, set owner.type to INDIVIDUAL and provide firstName and lastName instead of legalName. To fix a rejected field after creation, use PATCH /v1/accounts/{accountId} to replace the owner profile before submitting for review.A virtual account’s document set is the compliance baseline. You only provide additional documents when the owner handles third-party funds as a regulated payment entity. Whatever applies is listed in
requirements.currentlyDue. See BRL virtual accounts for details.2
Upload required documents
The creation response includes a Returns
requirements.currentlyDue array listing every document you need to provide. Each item carries a type discriminator. ACCOUNT_DOCUMENT and UBO_DOCUMENT name a specific documentType, while IDENTITY_VERIFICATION and INCORPORATION_DOCUMENT are grouped requirements whose options array lists the acceptable document types together with the subTypes and requiredMetadata each option needs. Upload documents against the /v1/accounts/{accountId}/documents endpoint, setting holder.type to ACCOUNT and holder.referenceId to the account ID:204 No Content. Upload one document per request, repeating for every requirement listed in currentlyDue.3
Add beneficial owners (company accounts)
Company-owned accounts require at least one beneficial owner (UBO). Register each UBO with their identity, contact, and address details. The response includes the UBO’s
phone and email are required so we can reach the UBO for follow-up during compliance review.id, which you’ll need for uploading their documents. Individual accounts have no UBOs, so skip this step and the next one.4
Upload UBO documents
Each UBO needs identity documents. Use the same Returns
/v1/accounts/{accountId}/documents endpoint, this time setting holder.type to UBO and holder.referenceId to the UBO’s id. Identity documents typically require a documentSubType (for example FRONT_SIDE or BACK_SIDE) and a metadata.country:204 No Content. Repeat for every side and every UBO registered on the account.5
Submit for review
Once all required documents are uploaded, submit the account for compliance review. This endpoint has no request body:Returns
202 Accepted. The account transitions from ACTION_REQUIRED to REVIEWING. If any documents are still missing or rejected, the API returns 422 with a MISSING_DOCUMENTS_FOR_REVIEW error listing the outstanding documentType names.6
Wait for activation
After review is approved, each asset activates on its own pipeline. The crypto wallet always activates first, since it has no manual steps, but the crypto wallet activating does not move the account to
ACTIVE. The account moves through OPENING and becomes ACTIVE only once a fiat asset finishes onboarding. Subscribe to the ACCOUNT_ASSET_ACTIVATED and ACCOUNT_ASSET_FAILED webhooks to react as each asset finishes, or poll GET /v1/accounts/{accountId}. Each entry in the response’s assets array carries its own provider-account status (ONBOARDING, ACTIVE, FAILED, FROZEN, DEACTIVATED) so you can see which assets are ready.7
Retrieve funding instructions
Once the account is active, retrieve the incoming transfer details for each active asset:For a virtual account, the Pix key is issued by Trace Finance rather than the account owner. Trace may share one key across virtual accounts, so route inbound funds using the
Response
accountIdentifier returned alongside the key. Filter the catalog with the optional asset and rail query parameters when you only need one rail for an asset.What happens next
- Make a deposit — fund the account with BRL or crypto.
- Execute a swap — convert between the account’s assets.