BRL VA Opening

Audience: Merchant Open API integrators
Related APIs:
# Document Method Path
1 Create Virtual Account POST /v1/virtual-account/sub/create
2 Get VA Detail GET /v1/virtual-account/sub/get
3 Open Virtual Account Status Webhook —

#	Document	Method	Path
1	Create Virtual Account	`POST`	`/v1/virtual-account/sub/create`
2	Get VA Detail	`GET`	`/v1/virtual-account/sub/get`
3	Open Virtual Account Status	Webhook	—

Opening a BRL (Brazilian Real) VA requires the beneficiary to pass onboarding review before the account can receive funds. The profile is small — a name, a tax identification number and a country — and no documents are uploaded.

1. Flow

Opening a BRL VA is asynchronous. One request carries both the account request and the beneficiary profile; the account is created only after the profile passes review.

Important — A 200 response means the application was accepted, not that the account exists. No PIX key or QR code is returned at submit time. Do not present receiving details to your end user until the account reaches SUCCESS.

No file upload step exists on the BRL path. Do not call Request File Upload URL when opening a BRL VA, and do not send documents or persons.

2. Request

The request shape is the one published on Create Virtual Account. Use the two examples named BRL-Woovi STATIC for Individual and BRL-Woovi STATIC for Company as the reference payloads; they are reproduced below.

2.1 Individual

{
  "primaryAccountId": "10001",
  "accountName": "John Doe",
  "currency": "BRL",
  "accountSubType": "STATIC",
  "userType": "Individual",
  "individualInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "taxIdNumber": "12345678900",
    "residenceCountry": "BR"
  }
}

Field	Rule
`primaryAccountId`	Master VA the sub account belongs to
`accountName`	Name of the account holder. Names the resulting account in queries and reconciliation
`currency`	`BRL`
`accountSubType`	`STATIC`
`userType`	`Individual`
`individualInfo.firstName`	Given name
`individualInfo.lastName`	Family name
`individualInfo.taxIdNumber`	The beneficiary's CPF
`individualInfo.residenceCountry`	Country of tax residence, ISO 3166-1 alpha-2 (`BR`)

2.2 Company

{
  "primaryAccountId": "10001",
  "currency": "BRL",
  "companyName": "Test Company",
  "accountSubType": "STATIC",
  "userType": "Corporate",
  "companyInfo": {
    "taxIdNumber": "12345678900",
    "incorporatedCountry": "BR"
  }
}

Field	Rule
`primaryAccountId`	Master VA the sub account belongs to
`currency`	`BRL`
`companyName`	Registered legal name. Names the resulting account; the company name is not read from `companyInfo`
`accountSubType`	`STATIC`
`userType`	`Corporate`
`companyInfo.taxIdNumber`	The company's CNPJ
`companyInfo.incorporatedCountry`	Country of tax residence, ISO 3166-1 alpha-2 (`BR`)

2.3 Response

{
  "status": 200,
  "msg": "OK",
  "code": null,
  "data": {
    "virtualAccountId": "40988",
    "currency": "BRL",
    "status": "INIT",
    "failReason": null
  },
  "traceId": "5b1e7d3c9a2f4e6b5b1e7d3c9a2f4e6b"
}

Keep virtualAccountId — it is the handle for the status query below.

3. Track the result

Two channels, use both:

Webhook. Subscribe to Open Virtual Account Status. It is delivered when the account reaches a terminal state. Deduplicate on eventId and treat the event as a prompt to query rather than as the source of truth.

Query. Call Get VA Detail (GET /v1/virtual-account/sub/get) with the virtualAccountId from the create response. Keep a scheduled query as a fallback in case a webhook is delayed or missed.

`status`	Meaning	Merchant action
`INIT`	Application accepted, not yet submitted for review	Wait
`PROCESSING`	Account under review	Wait
`SUCCESS`	Account created and usable	PIX key and QR code are available; the account may now receive funds
`FAIL`	Application rejected, or account creation failed	Read `failReason`, correct, submit a new application

At SUCCESS the account carries pixKeyType, pixKey, qrCode and qrCodeImage. These are absent at every earlier status.

Review turnaround is measured in business days, not seconds. Do not block a user-facing request on the outcome, and do not instruct anyone to remit funds before SUCCESS.

4. Differences from VND opening

	BRL	VND
Profile size	4 fields (individual) / 2 fields plus `companyName` (company)	12 fields (individual) / company profile, documents and persons (company)
Documents	None	Required for a company application, referenced by `fileId`
File upload step	Not used	Required before a company application
People behind the company	Not collected	`persons[]`, exactly one legal representative
Receiving details at `SUCCESS`	PIX key and QR code	Bank account details

Both currencies share the same endpoint, the same envelope, the same four statuses, and the same rule that a 200 is an accepted application rather than a usable account.

1. Flow#

2. Request#

2.1 Individual#

2.2 Company#

2.3 Response#

3. Track the result#