Overview
A named account is a fiat account held in the account owner’s name. UseNAMED for Brazilian residents and NAMED_NON_RESIDENT for non-residents. Every account is multi-currency, so crypto support is always included alongside the fiat assets you enable.
Named accounts follow Trace Finance’s compliance baseline and add segment-specific information and documents on top, depending on the owner’s profile (payment facilitators, non-residents, startups, crypto businesses, funds, and exchange operators). The exact set for your account is always returned in requirements.currentlyDue when you create it. See BRL named 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 document checklist for the owner’s segment. See BRL named 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 NAMED, or to NAMED_NON_RESIDENT for a non-resident owner. 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.Named accounts often require additional segment-specific documents, for example for payment facilitators, non-residents, startups, crypto businesses, funds, or exchange operators. Whatever applies to your account is listed in
requirements.currentlyDue. See BRL named accounts for the full breakdown by segment.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 named account, the BRL Pix key is registered in the account owner’s name, so
Response
keyType reflects the owner’s tax ID (CNPJ for a company, CPF for an individual). 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.