Creating a virtual account for a company

Creating a virtual account for a company

Provision a virtual bank account for a company (a legal entity / persona jurídica). The onboarding follows the same shape as an individual user, plus the company's corporate data, its shareholders, and its legal representatives — each representative completing a full identity verification.

📘

Currently available for Brazil (BRAZIL) companies identified by CNPJ, over BRL (PIX) rails. Other jurisdictions are not yet supported.


Prerequisites

  1. Register the company by calling POST /wallet/v1/onboarding-actions/simple with type: "BUSINESS", the company's legalId (CNPJ), its corporate data, its shareholders, and its beneficiaries (legal representatives). The company is created in ONBOARDING status.
  2. Each legal representative is created as its own user and must complete identity verification (see Upload onboarding documentation).
  3. Background compliance and screening checks run asynchronously for the company and every representative — no extra client-side steps are required.
  4. Once the company transitions to ACTIVE, the virtual account can be assigned.

Company data

The company is identified by its top-level legalId (CNPJ) and reached at its email or phoneNumber — at least one contact is required. For a BUSINESS user the personalData object carries the corporate data instead of individual fields:

FieldDescription
legalNameLegal / registered company name (razão social)
tradeNameTrade name (nome fantasia)
legalTypeCompany legal form. Free-text — send the value you use (e.g. LTDA, EI, MEI, EIRELI, SLU, SA, SS, COOP, SAS, LTD). Recognised forms and their common variants are normalised; unrecognised values are accepted and stored as sent.
constitutionDateIncorporation date (YYYY-MM-DD)
revenueDeclared annual revenue
addressstreet, numeration, postalCode, locality, province (country, neighborhood optional)

Most corporate fields are auto-populated from official records using the CNPJ (see Data auto-population); send a field only to override or fill what the registry does not return. Registry-only codes — cnae (CNAE), legalNatureCode (natureza jurídica) and stateRegistration — are always derived from the CNPJ and are not part of the payload. address is the exception: like an individual's, it's validated against official records rather than overridden — a complete, valid address you send is kept as-is; any field that is missing or doesn't check out is filled in or corrected automatically.


Shareholders

The shareholders array declares the ownership structure (quadro de sócios). At least one shareholder is required and the sum of participationPercentage must not exceed 100.

FieldDescription
externalIdOptional — your own identifier for this shareholder
legalIdShareholder document — CPF (individual) or CNPJ (company)
nameShareholder name (or legal name if a company)
typePARTNER, ATTORNEY, ADMINISTRATOR, or OTHER
participationPercentageOwnership percentage
representedByOptional — legalId of the legal representative acting for this shareholder. Only needed when the company declares more than one representative. See Linking shareholders and representatives.

A shareholder that is itself a company (CNPJ) is screened as-is — one level only; its own shareholders are not required. Its natural-person representative must be declared in beneficiaries.

📘

Shareholders are declared and screened only — they never upload documents. Identity documents are uploaded per legal representative (the beneficiaries array), not per shareholder. See Upload onboarding documentation.


Legal representatives

The beneficiaries array declares the legal representatives — the natural persons who act on behalf of the company. Legal representative and beneficiaries name the same thing: the first is the role, the second is the field that carries it in the payload. At least one legal representative is required. Each one completes a full identity verification, like an individual user.

FieldDescription
externalIdOptional — your own identifier for this representative; used as userAnyId to upload its documents. If omitted, use the numberId from the onboarding response instead.
legalIdRepresentative CPF
name, surnameFull name
addressRepresentative's full address (street, numeration, postalCode, locality, province)
representorTypeOptional — PARTNER, ATTORNEY, ADMINISTRATOR, or OTHER. Defaults to the type of the representative's own shareholder entry (same CPF, so this is automatic for the common self-representing case) — ADMINISTRATOR when the representative isn't a shareholder itself. Send it only to override that default.
email, phoneNumberContact details. Send at least one of the two.
relationshipStartDateOptional. When the representative's relationship with the company began (YYYY-MM-DD). If omitted, defaults to the company's incorporation date.
isPepOptional — politically exposed person

Like an individual user, a legal representative's identity data is pulled from the CPF: fields such as birth date and mother's name are auto-populated and are not part of the payload. name and surname are taken as sent. address is validated against official records: a complete, valid address you send is kept as-is; any field that is missing or doesn't check out is filled in or corrected automatically.


Linking shareholders and representatives

Every shareholder that needs one is matched to a legal representative. In the common case — a single representative for the whole company — you send nothing: the link is resolved for you.

SituationWhat you send
One legal representativeNothing. Every shareholder that needs a representative is matched to it.
More than one legal representativerepresentedBy on each CNPJ shareholder, carrying the legalId of the representative acting for it.

Two rules shape the result:

  • A natural-person (CPF) shareholder can only be matched to the representative that shares its own CPF. When the same person is both a shareholder and a representative, the link is automatic. When no representative shares that CPF, the shareholder is left unmatched — that is valid and blocks nothing.
  • A company (CNPJ) shareholder must end up matched to a representative. With a single representative that happens on its own; with several, send representedBy or the request is rejected with INVALID_REPRESENTATIVES.

A representative that is not a shareholder — someone acting for the company itself rather than for one of its partners — needs no representedBy anywhere. Declare it in beneficiaries and nothing else is required.

📘

Sending representedBy on a CPF shareholder pointing at a representative with a different CPF is rejected: that link cannot exist.

Examples

Three shareholders, one representative. Nothing to send — this is the common case.

"shareholders": [
  { "legalId": "12345678909", "name": "JOHN DOE", "type": "PARTNER", "participationPercentage": 50 },
  { "legalId": "52998224725", "name": "ANA SOUZA", "type": "PARTNER", "participationPercentage": 30 },
  { "legalId": "11144477735", "name": "CARLOS LIMA", "type": "PARTNER", "participationPercentage": 20 }
],
"beneficiaries": [
  { "legalId": "12345678909", "name": "JOHN", "surname": "DOE", "email": "[email protected]" }
]

John is matched to his own shareholder entry, because they share a CPF. Ana and Carlos stay unmatched — valid: they are screened as shareholders and upload nothing.

Mixed shareholders, one representative. Still nothing to send.

"shareholders": [
  { "legalId": "12345678909", "name": "JOHN DOE", "type": "PARTNER", "participationPercentage": 50 },
  { "legalId": "11222333000181", "name": "HOLDING EXEMPLO LTDA", "type": "PARTNER", "participationPercentage": 50 }
],
"beneficiaries": [
  { "legalId": "12345678909", "name": "JOHN", "surname": "DOE", "email": "[email protected]" }
]

The CNPJ shareholder needs a representative and only one is declared, so it is matched automatically.

Mixed shareholders, two representatives. representedBy is required on the CNPJ shareholder.

"shareholders": [
  { "legalId": "12345678909", "name": "JOHN DOE", "type": "PARTNER", "participationPercentage": 50 },
  { "legalId": "11222333000181", "name": "HOLDING EXEMPLO LTDA", "type": "PARTNER", "participationPercentage": 50, "representedBy": "52998224725" }
],
"beneficiaries": [
  { "legalId": "12345678909", "name": "JOHN", "surname": "DOE", "email": "[email protected]" },
  { "legalId": "52998224725", "name": "ANA", "surname": "SOUZA", "email": "[email protected]" }
]

With two representatives the automatic match is ambiguous, so the CNPJ shareholder names its own. John still sends nothing — he shares a CPF with his shareholder entry. Omitting representedBy here is rejected with INVALID_REPRESENTATIVES.


Request example

curl -X POST https://sandbox.manteca.dev/wallet/v1/onboarding-actions/simple \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "externalId": "company-001",
      "type": "BUSINESS",
      "legalId": "12345678000190",
      "legalIdDocumentType": "CNPJ",
      "legalIdNationality": "BRAZIL",
      "email": "[email protected]",
      "personalData": {
        "legalName": "EMPRESA EXEMPLO LTDA",
        "tradeName": "Empresa Exemplo",
        "legalType": "LTDA",
        "constitutionDate": "2015-06-10",
        "revenue": 5000000,
        "address": {
          "street": "AVENIDA PAULISTA",
          "numeration": "1000",
          "postalCode": "01310100",
          "locality": "SAO PAULO",
          "province": "SP"
        }
      },
      "shareholders": [
        {
          "externalId": "john-doe",
          "legalId": "12345678909",
          "name": "JOHN DOE",
          "type": "PARTNER",
          "participationPercentage": 70
        },
        {
          "externalId": "shareholder-002",
          "legalId": "98765432000110",
          "name": "HOLDING EXEMPLO LTDA",
          "type": "PARTNER",
          "participationPercentage": 30,
          "representedBy": "52998224725"
        }
      ],
      "beneficiaries": [
        {
          "externalId": "john-doe",
          "legalId": "12345678909",
          "name": "JOHN",
          "surname": "DOE",
          "email": "[email protected]",
          "phoneNumber": "5511990001234",
          "isPep": false,
          "relationshipStartDate": "2015-06-10",
          "address": {
            "street": "RUA EXEMPLO",
            "numeration": "200",
            "postalCode": "01000000",
            "locality": "SAO PAULO",
            "province": "SP"
          }
        },
        {
          "externalId": "ana-souza",
          "legalId": "52998224725",
          "name": "ANA",
          "surname": "SOUZA",
          "email": "[email protected]",
          "phoneNumber": "5511990005678",
          "isPep": false,
          "relationshipStartDate": "2018-03-01",
          "address": {
            "street": "AVENIDA FARIA LIMA",
            "numeration": "500",
            "postalCode": "01451000",
            "locality": "SAO PAULO",
            "province": "SP"
          }
        }
      ]
  }'

Onboarding response

The response echoes the created shareholders and legal representatives, alongside the externalId and legalId you sent. A shareholder only gets a numberId when its legalId is also declared in beneficiaries — shareholders are screened only, never onboarded as their own user (see Shareholders), so a shareholder that isn't also a representative has no numberId of its own. Use either the externalId or the numberId as the userAnyId when uploading a representative's documents.

{
  "userAnyId": "100012345",
  "status": "ONBOARDING",
  "shareholders": [
    { "externalId": "john-doe", "legalId": "12345678909", "numberId": "100012346" },
    { "externalId": "shareholder-002", "legalId": "98765432000110" }
  ],
  "beneficiaries": [
    { "externalId": "john-doe", "legalId": "12345678909", "numberId": "100012346" },
    { "externalId": "ana-souza", "legalId": "52998224725", "numberId": "100012348" }
  ]
}
📘

A person who appears as both a shareholder and a legal representative (same legalId) is a single user — note the shared numberId above. Provide the same externalId (or omit it) in both entries. Sending different externalId values for the same legalId is rejected. shareholder-002 above (HOLDING EXEMPLO LTDA) has no numberId: it's represented by Ana (representedBy) but was never itself declared as a legal representative.


Upload onboarding documentation

A company virtual account requires two sets of documents: the company's corporate documents, and the identity documents for each legal representative. There is one endpoint per document type. Each file is uploaded in two steps — request a short-lived pre-signed URL, then PUT the file straight to it (see the individual flow for the two-step mechanics).

Company documents (uploaded against the company userAnyId):

DocumentEndpointNotes
Articles of incorporationPOST /wallet/v1/onboarding-actions/upload-articles-of-incorporation-documentationContrato social / estatuto — the company's articles of incorporation.
Financial statementPOST /wallet/v1/onboarding-actions/upload-financial-statement-documentationBalance sheet or income statement (DRE).
Revenue declaration (optional)POST /wallet/v1/onboarding-actions/upload-revenue-declaration-documentationOptional. Proof of active CNPJ financial use (REVENUE_DECLARATION). The company's revenue is already covered by the financial statement, so this is not required.

Fiscally exposed companies (Sujetos Obligados) must additionally upload their AML/KYC policy — see Fiscally exposed companies below. A company flagged as politically exposed needs no extra document at all — see Politically exposed companies.

Per legal representative (against each representative's userAnyId — its externalId from your payload, or the numberId from the onboarding response). A representative completes the same identity verification as an individual user, plus a proof of address:

StepEndpointNotes
Identity documentPOST /wallet/v1/onboarding-actions/upload-identity-imageOne request per side — both FRONT and BACK.
Liveness checkPOST /wallet/v1/onboarding-actions/perform-external-liveness or upload-liveness-video-documentationRequires the representative's personal data and identity document already submitted. Either hand the returned link to the representative or upload a video you recorded with them — the two routes are interchangeable. See the individual flow.
Proof of addressPOST /wallet/v1/onboarding-actions/upload-proof-of-address-documentationComprovante de residência (PROOF_OF_ADDRESS).
Proof of source of fundsPOST /wallet/v1/onboarding-actions/upload-pep-documentation or upload-fep-documentationOnly for representatives flagged as politically or fiscally exposed. A representative is an individual, so the individual PEP/FEP rule applies to it: one document, either endpoint, against the representative's own userAnyId.

The company transitions to ACTIVE only once its corporate data is complete, its documents are uploaded, every shareholder is registered and screened, and every legal representative has completed its identity verification. Progress is tracked with the SHAREHOLDERS_ACTIVE and LEGAL_REPRESENTATIVES_ACTIVE onboarding tasks — see that page for what each company and representative task means and how it completes.

Politically exposed companies

If the screening flags the company itself as politically exposed, PEP_DOCUMENTATION_VALIDATION becomes required on the company user — and the documents that satisfy it are ones you have already sent. Either the articles of incorporation (ESTATUTO) or the financial statement (BALANCE) completes it; either one on its own is enough, and both are required by IDENTITY_VALIDATION_BUSINESS anyway. In practice the task completes without a single extra call, including when the flag is raised after those documents were approved.

Two things this rule is not. It does not accept a proof of source of funds: that document satisfies the PEP task for an individual, not for a company. And it says nothing about the company's representatives — a representative flagged as PEP is an individual and follows the individual rule, against its own userAnyId.

Fiscally exposed companies

If Manteca's screening classifies the company as a fiscally exposed entity (Sujeto Obligado) — this is determined automatically during screening, not declared by you — it must upload its AML/KYC policy. This uses the same FEP flow as individual users: request the upload URL with POST /wallet/v1/onboarding-actions/upload-fep-documentation against the company userAnyId, then PUT the file to the returned URL. The upload completes the FEP_DOCUMENTATION_VALIDATION onboarding task; the result is delivered through the onboarding webhook (see Checking onboarding status).


Data auto-population

For Brazilian companies, corporate data (legal name, trade name, legal type, incorporation date, and the shareholder structure) is pulled automatically from official records using the CNPJ. Send a field only to fill or override what the registry does not return. address is validated rather than overridden: a complete, valid address you send is kept as-is; any field that is missing or doesn't check out is filled in or corrected automatically.


Checking onboarding status

Track each member's progress with GET /wallet/v1/users/USERANYID, using the numberId (or externalId) from the onboarding response. The company only reaches ACTIVE once every shareholder and legal representative does.

curl https://sandbox.manteca.dev/wallet/v1/users/100012346 \
  -H "md-api-key: $MD_API_KEY"
{
  "numberId": "100012346",
  "externalId": "john-doe",
  "status": "ONBOARDING",
  "onboarding": [
    { "task": "IDENTITY_VALIDATION", "status": "COMPLETED" },
    { "task": "EXTERNAL_LIVENESS_VALIDATION", "status": "PENDING" }
  ]
}

Poll each representative to see which tasks are still PENDING, then complete the liveness check through either route or re-upload the document as needed. Query the company userAnyId the same way to see its own tasks (SHAREHOLDERS_ACTIVE, LEGAL_REPRESENTATIVES_ACTIVE).

Because the company and each legal representative are separate users, each one emits its own webhooks as it advances — USER_ONBOARDING_UPDATE (per-task changes) and USER_WALLET_STATUS_UPDATE (overall status). Subscribe to these to track the company and every representative in parallel instead of polling. The event payload carries no parent link, so store the numberId of the company and of every member from the onboarding response and match incoming events by numberId to know which company a representative's event belongs to.

If a document is rejected, its onboarding task moves to FAILED (not PENDING): request a fresh upload URL for that document and re-PUT the corrected file. The member — and therefore the company — cannot reach ACTIVE until every task is COMPLETED.

📘

The register request is rejected up front on invalid corporate input — the sum of participationPercentage exceeding 100, a missing shareholder or legal representative, or the same legalId sent with conflicting externalId values across shareholders and beneficiaries.


Create the account

Once the company is ACTIVE, assign the virtual account exactly as for an individual user, using the company userAnyId:

curl -X POST https://sandbox.manteca.dev/wallet/v1/user-actions/assign-virtual-account \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "userAnyId": "100012345",
      "asset": "BRL",
      "externalId": "company-acc-brl-001"
  }'

Account creation is asynchronous. The account starts in PENDING and transitions to ACTIVE once the banking network confirms it. Listen for the VIRTUAL_ACCOUNT_STATUS_UPDATE webhook or poll GET /wallet/v1/accounts/{accountAnyId} — see Creating a virtual account → Wait for activation.

Once ACTIVE, the account's address and alias hold the company's PIX key and bank details — share them to start receiving deposits (see Share the account address).


Related


Did this page help you?