> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar subconta

> Cadastra uma subconta ligada à sua conta master, com dados da empresa, representante legal, sócios e conta bancária.

Esta rota cria uma subconta (SubMerchant) da Finvia vinculada à sua conta master (MerchantMaster) no [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md). É o primeiro passo para colocar um vendedor, franqueado ou parceiro para receber pagamentos dentro da sua plataforma. A subconta nasce em análise (`pending`) e só pode transacionar depois de aprovada no credenciamento (KYC, a verificação de identidade da empresa e dos sócios).

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Vendedor novo se cadastra na sua plataforma | Envie os dados da empresa, o representante legal e a conta bancária |
| Empresa com mais de um sócio | Envie também `additionalRepresentatives` e guarde os `id` devolvidos em `legalRepresentatives` |
| O vendedor vai usar o painel da Finvia | `canAccessDashboard: true` e o objeto `user` |
| O vendedor só vai operar pelo seu sistema | `canAccessDashboard: false`, sem `user` |
| Consultar uma subconta já criada | Use [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md) |

## Antes de chamar

* O módulo Connect precisa estar habilitado pela Finvia na sua conta master. Sem isso, a resposta é `403` `Fast Connect not enabled.`.
* Autentique com a chave secreta (`sk_`) da **conta master** ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* Pré-valide o cadastro do lojista do seu lado antes de enviar, como pedem as [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md).
* Tenha em mãos os dados da empresa, do representante legal (e dos demais sócios, se houver) e da conta bancária de recebimento.
* Os documentos (cartão CNPJ, contrato social, documento com foto e selfie) **não** vão nesta chamada. Eles são enviados depois, com o `id` devolvido aqui ([Sócios e documentos](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md)).

> [!NOTE]
>
> **Para o negócio:** na criação, a subconta recebe uma cópia das taxas e configurações vigentes da conta master. Depois disso, as taxas da subconta são independentes: mudar as taxas da master não altera as das subcontas já criadas. As taxas de cada subconta podem ser consultadas em [Taxas e dados da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/taxas-e-dados.md).

## Corpo da requisição

Campos obrigatórios: `legalName`, `tradeName`, `companyTaxId`, `website`, `averageMonthlyRevenue`, `averageOrderValue`, `productType`, `legalRepresentative`, `contactEmail`, `productDescription`, `address`, `phones`, `bankAccount` e `canAccessDashboard`.

### Dados da empresa

**legalName** `string` *required*

Razão social. Ex.: `LOJA EXEMPLO LTDA`.

**tradeName** `string` *required*

Nome fantasia. Ex.: `Loja Exemplo`.

**companyTaxId** `string` *required*

CNPJ da empresa, com ou sem máscara. Quando `address.country` é `BRA`, precisa ser um CPF ou CNPJ com dígito verificador válido. O valor é gravado só com dígitos. Ex.: `11.222.333/0001-81`.

**website** `string` *required*

Site da empresa (formato `uri`). Informe a URL onde estão os produtos ou serviços que serão vendidos: ela é conferida no credenciamento. Ex.: `https://loja.exemplo.com.br`.

**averageMonthlyRevenue** `number` *required*

Expectativa de faturamento médio mensal, em reais. Ex.: `30000`.

**averageOrderValue** `number` *required*

Ticket médio por pedido, em reais. Ex.: `150`.

**productType** `string` *required*

Tipo de produto vendido: `digital`, `physical` ou `both`. Ex.: `physical`.

**contactEmail** `string` *required*

E-mail de contato da empresa. Ex.: `contato@lojaexemplo.com.br`.

**productDescription** `string` *required*

Descrição curta dos produtos ou serviços. Ex.: `Roupas e acessórios femininos`.

**softDescriptor** `string`

Nome que aparece na fatura do cartão do cliente. Máximo de 40 caracteres (`maxLength` 40). Ex.: `LOJAEXEMPLO`.

**address** `object` *required*

Endereço da empresa. O país define as regras dos outros campos (veja a tabela abaixo).

**propriedades**

**addressLine1** `string` *required*

Logradouro e número, separados por vírgula, com o número no fim. Ex.: `Av. Paulista, 1000`. O número é extraído desse formato para o credenciamento nas adquirentes. Sem vírgula e número no fim, ele pode ser enviado como "S/N".

**addressLine2** `string`

Complemento (apartamento, sala, bloco, andar). Opcional; se omitido, é gravado vazio. Ex.: `Sala 12`.

**referencePoint** `string`

Ponto de referência do endereço. Opcional, até 255 caracteres. Ex.: `Próximo à estação Trianon-Masp`.

**neighborhood** `string` *required*

Bairro. Obrigatório quando o país é `BRA`. Ex.: `Bela Vista`.

**city** `string` *required*

Cidade. Ex.: `São Paulo`.

**state** `string` *required*

Estado. Quando o país é `BRA`, precisa ser uma UF válida. Ex.: `SP`.

**country** `string` *required*

País, em ISO 3166-1 alpha-3 (três letras maiúsculas, padrão `^[A-Z]{3}$`). Ex.: `BRA`. O formato alpha-2 (`BR`) é recusado com `400`.

**postalCode** `string` *required*

CEP. Quando o país é `BRA`, precisa ter 8 dígitos. Ex.: `01310100`.

**phones** `object[]` *required*

Telefones da empresa.

**propriedades**

**type** `string` *required*

Tipo do telefone. Ex.: `mobile`.

**number** `string` *required*

Número do telefone. Ex.: `+5511987654321`.

#### Regras que dependem do país

| Campo | Quando o país do endereço é `BRA` |
| - | - |
| `companyTaxId` | CPF ou CNPJ com dígito verificador válido |
| `address.state` | UF válida (ex.: `SP`) |
| `address.postalCode` | CEP com 8 dígitos |
| `address.neighborhood` | Obrigatório |
| `idNumber` do representante e dos sócios | CPF válido quando `issuingCountry` é `BRA` ou não é enviado |

Todos os campos de país da subconta usam ISO 3166-1 alpha-3: `address.country`, `address.country` do representante e dos sócios, e `issuingCountry`. A validação não diferencia maiúsculas de minúsculas, mas o valor é gravado como foi enviado: envie sempre em maiúsculas.

### Representante legal e sócios

**legalRepresentative** `object` *required*

Representante legal da empresa. É sempre o representante principal da subconta (`isPrimary: true`), e os documentos de pessoa enviados sem indicar um sócio ficam ligados a ele.

**propriedades**

**fullName** `string` *required*

Nome completo. Ex.: `Ana Lima`.

**dateOfBirth** `string` *required*

Data de nascimento (formato `date`). Ex.: `1988-04-12`.

**nationality** `string` *required*

Nacionalidade, em texto livre (não é código de país). Ex.: `Brasileira`.

**idNumber** `string` *required*

Número do documento. Precisa ser um CPF válido quando `issuingCountry` é `BRA` ou não é enviado. Ex.: `52998224725`.

**idType** `string`

Tipo do documento de identificação. Ex.: `cpf`.

**issuingCountry** `string`

País emissor do documento, em ISO 3166-1 alpha-3. Opcional. Ex.: `BRA`.

**email** `string` *required*

E-mail. Ex.: `ana.lima@email.com`.

**motherName** `string` *required*

Nome da mãe. Ex.: `Maria Lima`.

**gender** `string` *required*

Gênero: `M` ou `F`.

**address** `object`

Endereço próprio do representante. Opcional: sem ele, o representante usa o endereço da empresa. Quando enviado, `country` é obrigatório.

**propriedades**

**addressLine1** `string` *required*

Logradouro e número, separados por vírgula. Ex.: `Rua Augusta, 500`.

**addressLine2** `string`

Complemento. Opcional. Ex.: `Apto 31`.

**neighborhood** `string` *required*

Bairro. Ex.: `Consolação`.

**city** `string` *required*

Cidade. Ex.: `São Paulo`.

**state** `string` *required*

Estado. Ex.: `SP`.

**country** `string` *required*

País, em ISO 3166-1 alpha-3. Ex.: `BRA`.

**postalCode** `string` *required*

CEP. Ex.: `01305000`.

**phones** `object[]` *required*

Telefones do representante.

**propriedades**

**type** `string` *required*

Tipo do telefone. Ex.: `mobile`.

**number** `string` *required*

Número do telefone. Ex.: `+5511987654321`.

**additionalRepresentatives** `object[]`

Sócios adicionais da empresa (opcional). Cada item tem o **mesmo formato** do `legalRepresentative`, com as mesmas regras de país e de CPF. O `legalRepresentative` continua obrigatório e é sempre o representante legal; os adicionais são cadastrados como sócios. Os documentos dos sócios não vão neste corpo: depois da criação, use os `id` devolvidos em `legalRepresentatives` para enviar os documentos de cada sócio com [token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md).

> [!NOTE]
>
> O campo `referencePoint` só é gravado no endereço da empresa. No endereço próprio do representante ou de um sócio ele é aceito, mas descartado.

### Conta bancária

**bankAccount** `object` *required*

Conta bancária da subconta. Todos os campos são obrigatórios, exceto `routingNumber`.

**propriedades**

**bankCode** `string` *required*

Código do banco. Ex.: `001`.

**agencyCode** `string` *required*

Agência. Ex.: `1234`.

**accountNumber** `string` *required*

Número da conta. Ex.: `567890`.

**accountDigit** `string` *required*

Dígito da conta. Ex.: `0`.

**accountType** `string` *required*

Tipo da conta: `checking` (corrente) ou `savings` (poupança).

**bankName** `string` *required*

Nome do banco. Ex.: `Banco do Brasil`.

**recipientName** `string` *required*

Nome do titular da conta. Ex.: `LOJA EXEMPLO LTDA`.

**recipientDocument** `string` *required*

CPF ou CNPJ do titular da conta, validado pelos dígitos verificadores. Ex.: `11222333000181`.

**routingNumber** `string`

Routing number, para contas dos Estados Unidos. Opcional.

> [!WARNING]
>
> `companyTaxId`, `idNumber` (do representante e dos sócios) e `bankAccount.recipientDocument` são validados pelos dígitos verificadores. Os números dos exemplos desta página são válidos só para teste de formato: na sua integração, envie os documentos reais do lojista.

### Acesso ao painel e notificações

**canAccessDashboard** `boolean` *required*

Define se a subconta pode acessar o painel da Finvia. Ex.: `true`.

**user** `object`

Usuário que vai acessar o painel. **Obrigatório quando `canAccessDashboard` é `true`.** Quando o objeto é enviado, os três campos são obrigatórios. Se o e-mail já tiver usuário cadastrado, a resposta é `400` `Email already registered`.

**propriedades**

**fullName** `string` *required*

Nome do usuário. Ex.: `Ana Lima`.

**email** `string` *required*

E-mail do usuário. Ex.: `ana.lima@email.com`.

**phone** `string` *required*

Telefone no formato internacional estrito (E.164). Ex.: `+5511987654321`.

**postbackUrl** `string`

URL (formato `uri`) para receber os avisos de mudança de status da subconta. Opcional. Ex.: `https://meusite.com.br/webhooks/finvia/conta`.

A URL fica salva nas configurações da subconta. Para alterá-la depois, fale com o suporte. Sem `postbackUrl`, a subconta usa a URL de aviso de status da conta master, se a master tiver uma. Esta URL não recebe eventos de cobrança. O aviso vem sem envelope, em camelCase, com `merchantId`, `status`, `date` e, quando o status é `rejected` ou `correcting`, `rejectionReason`. Veja [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md).

## Respostas

A resposta `201` traz só o `id` da subconta e os representantes criados. Para ver o cadastro completo, use [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md).

**id** `string` *required*

Identificador da subconta criada. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`. Guarde este valor: ele é usado para enviar documentos, consultar a subconta, obter as chaves de API e pedir saques.

**legalRepresentatives** `object[]`

Representantes criados: o **representante legal primeiro** (`isPrimary: true`) e depois os sócios adicionais, na ordem enviada. Use os `id` dos itens com `isPrimary: false` para enviar os documentos de cada sócio.

**propriedades**

**id** `string`

Identificador do representante ou sócio. Ex.: `2vorkEaaaBbbCccDddEeeFffGgg`.

**fullName** `string`

Nome completo. Ex.: `Ana Lima`.

**isPrimary** `boolean`

`true` apenas no representante legal da empresa.

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Subconta criada | `id`, `legalRepresentatives` |
| `400` | Corpo inválido, com `message` em lista | `{"statusCode": 400, "message": ["bankAccount.bankCode should not be empty"], "error": "Bad Request"}` |
| `400` | E-mail do usuário do painel já cadastrado (com `canAccessDashboard: true`) | `{"statusCode": 400, "message": "Email already registered", "error": "Bad Request"}` |
| `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` |
| `409` | CNPJ já cadastrado em outra subconta da mesma master (em qualquer status) ou igual ao CNPJ da própria master | `{"statusCode": 409, "message": "Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.", "error": "Conflict"}` |

As mensagens misturam português e inglês. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição.

> [!TIP]
>
> A criação deu certo quando a resposta é `201` com um `id`. A subconta começa em análise (`pending`) e só pode transacionar quando chegar a `active`.

## Depois de criar

**1. Envie os documentos**

Use [Enviar documentos](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos.md) para os documentos da empresa e do representante legal. Para cada sócio adicional, gere um [token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md) com o `id` dele. A lista de documentos exigidos está em [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md).

**2. Acompanhe a análise**

Receba os avisos de status no `postbackUrl` e consulte a subconta com [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md). Se o status for `correcting`, corrija os dados ou documentos pedidos.

**3. Obtenha as chaves**

Com a subconta `active`, busque as chaves dela em [Chaves de API da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/chaves-de-api.md) para criar cobranças em nome do vendedor.

## Exemplos por caso de uso

> [tab] Sócio único, sem painel
>
> Vendedor que opera só pela sua plataforma. O representante usa o endereço da empresa.
>
> ```json theme={null}
> {
>   "legalName": "LOJA EXEMPLO LTDA",
>   "tradeName": "Loja Exemplo",
>   "companyTaxId": "11.222.333/0001-81",
>   "website": "https://loja.exemplo.com.br",
>   "averageMonthlyRevenue": 30000,
>   "averageOrderValue": 150,
>   "productType": "physical",
>   "contactEmail": "contato@lojaexemplo.com.br",
>   "productDescription": "Roupas e acessórios femininos",
>   "softDescriptor": "LOJAEXEMPLO",
>   "address": {
>     "addressLine1": "Av. Paulista, 1000",
>     "addressLine2": "Sala 12",
>     "referencePoint": "Próximo à estação Trianon-Masp",
>     "neighborhood": "Bela Vista",
>     "city": "São Paulo",
>     "state": "SP",
>     "country": "BRA",
>     "postalCode": "01310100"
>   },
>   "phones": [{ "type": "mobile", "number": "+5511987654321" }],
>   "legalRepresentative": {
>     "fullName": "Ana Lima",
>     "dateOfBirth": "1988-04-12",
>     "nationality": "Brasileira",
>     "idNumber": "52998224725",
>     "idType": "cpf",
>     "issuingCountry": "BRA",
>     "email": "ana.lima@email.com",
>     "motherName": "Maria Lima",
>     "gender": "F",
>     "phones": [{ "type": "mobile", "number": "+5511987654321" }]
>   },
>   "bankAccount": {
>     "bankCode": "001",
>     "agencyCode": "1234",
>     "accountNumber": "567890",
>     "accountDigit": "0",
>     "accountType": "checking",
>     "bankName": "Banco do Brasil",
>     "recipientName": "LOJA EXEMPLO LTDA",
>     "recipientDocument": "11222333000181"
>   },
>   "canAccessDashboard": false,
>   "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
> }
> ```

> [tab] Dois sócios, com painel
>
> Empresa com um sócio adicional, que tem endereço próprio. O vendedor também terá acesso ao painel da Finvia.
>
> ```json theme={null}
> {
>   "legalName": "LOJA EXEMPLO LTDA",
>   "tradeName": "Loja Exemplo",
>   "companyTaxId": "11222333000181",
>   "website": "https://loja.exemplo.com.br",
>   "averageMonthlyRevenue": 12000,
>   "averageOrderValue": 100,
>   "productType": "both",
>   "contactEmail": "contato@lojaexemplo.com.br",
>   "productDescription": "Peças de cerâmica e aulas online",
>   "address": {
>     "addressLine1": "Av. Paulista, 1000",
>     "neighborhood": "Bela Vista",
>     "city": "São Paulo",
>     "state": "SP",
>     "country": "BRA",
>     "postalCode": "01310100"
>   },
>   "phones": [{ "type": "mobile", "number": "+5511987654321" }],
>   "legalRepresentative": {
>     "fullName": "Ana Lima",
>     "dateOfBirth": "1988-04-12",
>     "nationality": "Brasileira",
>     "idNumber": "52998224725",
>     "email": "ana.lima@email.com",
>     "motherName": "Maria Lima",
>     "gender": "F",
>     "phones": [{ "type": "mobile", "number": "+5511987654321" }]
>   },
>   "additionalRepresentatives": [
>     {
>       "fullName": "Joao Silva",
>       "dateOfBirth": "1985-05-10",
>       "nationality": "Brasileira",
>       "idNumber": "11144477735",
>       "idType": "cpf",
>       "issuingCountry": "BRA",
>       "email": "joao.silva@email.com",
>       "motherName": "Joana Silva",
>       "gender": "M",
>       "address": {
>         "addressLine1": "Rua Augusta, 500",
>         "addressLine2": "Apto 31",
>         "neighborhood": "Consolação",
>         "city": "São Paulo",
>         "state": "SP",
>         "country": "BRA",
>         "postalCode": "01305000"
>       },
>       "phones": [{ "type": "mobile", "number": "+5511987654321" }]
>     }
>   ],
>   "bankAccount": {
>     "bankCode": "001",
>     "agencyCode": "1234",
>     "accountNumber": "567890",
>     "accountDigit": "0",
>     "accountType": "checking",
>     "bankName": "Banco do Brasil",
>     "recipientName": "LOJA EXEMPLO LTDA",
>     "recipientDocument": "11222333000181"
>   },
>   "canAccessDashboard": true,
>   "user": {
>     "fullName": "Ana Lima",
>     "email": "ana.lima@email.com",
>     "phone": "+5511987654321"
>   }
> }
> ```
>
> Na resposta, o item com `isPrimary: false` é o sócio Joao Silva. Use o `id` dele ao gerar o token de upload dos documentos pessoais dele.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` `address.country must be a valid ISO31661 Alpha3 code` | País enviado em alpha-2 (`BR`) | Envie `BRA` |
| `400` no `companyTaxId` ou no `idNumber` | CNPJ ou CPF com dígito verificador inválido, com país `BRA` | Confira os documentos do lojista e dos sócios |
| `400` no CEP, na UF ou no bairro | Com país `BRA`, o CEP precisa ter 8 dígitos, a UF precisa ser válida e o bairro é obrigatório | Corrija o endereço |
| `400` com `canAccessDashboard: true` | Objeto `user` ausente ou incompleto, ou `user.phone` fora do E.164 | Envie `user` com `fullName`, `email` e `phone` (ex.: `+5511987654321`) |
| `400` `Email already registered` | Já existe usuário do painel com esse e-mail | Use outro e-mail em `user.email` |
| `409` com a mensagem de CNPJ já cadastrado | O CNPJ já existe em outra subconta sua, em qualquer status, ou é o CNPJ da master | Consulte a subconta existente em [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md) com `companyTaxId` |
| Número do endereço chega como "S/N" na adquirente | `addressLine1` sem vírgula e número no fim | Envie no formato `Av. Paulista, 1000` |
| Documentos do sócio ficaram no representante legal | Upload feito sem indicar o sócio | Use o fluxo com token informando o `legalRepresentativeId` do sócio |

```http REST (JSON) theme={null}
POST /v1/submerchants HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "legalName": "LOJA EXEMPLO LTDA",
  "tradeName": "Loja Exemplo",
  "companyTaxId": "11.222.333/0001-81",
  "website": "https://loja.exemplo.com.br",
  "averageMonthlyRevenue": 30000,
  "averageOrderValue": 150,
  "productType": "physical",
  "contactEmail": "contato@lojaexemplo.com.br",
  "productDescription": "Roupas e acessórios femininos",
  "softDescriptor": "LOJAEXEMPLO",
  "address": {
    "addressLine1": "Av. Paulista, 1000",
    "addressLine2": "Sala 12",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "country": "BRA",
    "postalCode": "01310100"
  },
  "phones": [
    {
      "type": "mobile",
      "number": "+5511987654321"
    }
  ],
  "legalRepresentative": {
    "fullName": "Ana Lima",
    "dateOfBirth": "1988-04-12",
    "nationality": "Brasileira",
    "idNumber": "52998224725",
    "issuingCountry": "BRA",
    "email": "ana.lima@email.com",
    "motherName": "Maria Lima",
    "gender": "F",
    "phones": [
      {
        "type": "mobile",
        "number": "+5511987654321"
      }
    ]
  },
  "additionalRepresentatives": [
    {
      "fullName": "Joao Silva",
      "dateOfBirth": "1985-05-10",
      "nationality": "Brasileira",
      "idNumber": "11144477735",
      "issuingCountry": "BRA",
      "email": "joao.silva@email.com",
      "motherName": "Joana Silva",
      "gender": "M",
      "phones": [
        {
          "type": "mobile",
          "number": "+5511987654321"
        }
      ]
    }
  ],
  "bankAccount": {
    "bankCode": "001",
    "agencyCode": "1234",
    "accountNumber": "567890",
    "accountDigit": "0",
    "accountType": "checking",
    "bankName": "Banco do Brasil",
    "recipientName": "LOJA EXEMPLO LTDA",
    "recipientDocument": "11222333000181"
  },
  "canAccessDashboard": true,
  "user": {
    "fullName": "Ana Lima",
    "email": "ana.lima@email.com",
    "phone": "+5511987654321"
  },
  "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "LOJA EXEMPLO LTDA",
    "tradeName": "Loja Exemplo",
    "companyTaxId": "11.222.333/0001-81",
    "website": "https://loja.exemplo.com.br",
    "averageMonthlyRevenue": 30000,
    "averageOrderValue": 150,
    "productType": "physical",
    "contactEmail": "contato@lojaexemplo.com.br",
    "productDescription": "Roupas e acessórios femininos",
    "softDescriptor": "LOJAEXEMPLO",
    "address": {
      "addressLine1": "Av. Paulista, 1000",
      "addressLine2": "Sala 12",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA",
      "postalCode": "01310100"
    },
    "phones": [{ "type": "mobile", "number": "+5511987654321" }],
    "legalRepresentative": {
      "fullName": "Ana Lima",
      "dateOfBirth": "1988-04-12",
      "nationality": "Brasileira",
      "idNumber": "52998224725",
      "issuingCountry": "BRA",
      "email": "ana.lima@email.com",
      "motherName": "Maria Lima",
      "gender": "F",
      "phones": [{ "type": "mobile", "number": "+5511987654321" }]
    },
    "additionalRepresentatives": [
      {
        "fullName": "Joao Silva",
        "dateOfBirth": "1985-05-10",
        "nationality": "Brasileira",
        "idNumber": "11144477735",
        "issuingCountry": "BRA",
        "email": "joao.silva@email.com",
        "motherName": "Joana Silva",
        "gender": "M",
        "phones": [{ "type": "mobile", "number": "+5511987654321" }]
      }
    ],
    "bankAccount": {
      "bankCode": "001",
      "agencyCode": "1234",
      "accountNumber": "567890",
      "accountDigit": "0",
      "accountType": "checking",
      "bankName": "Banco do Brasil",
      "recipientName": "LOJA EXEMPLO LTDA",
      "recipientDocument": "11222333000181"
    },
    "canAccessDashboard": true,
    "user": {
      "fullName": "Ana Lima",
      "email": "ana.lima@email.com",
      "phone": "+5511987654321"
    },
    "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
  }'
```

```javascript Node.js theme={null}
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch('https://api-global.fastpaybrasil.com/v1/submerchants', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${auth}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    legalName: 'LOJA EXEMPLO LTDA',
    tradeName: 'Loja Exemplo',
    companyTaxId: '11222333000181',
    website: 'https://loja.exemplo.com.br',
    averageMonthlyRevenue: 30000, // R$ 30.000,00 por mês
    averageOrderValue: 150, // R$ 150,00 por pedido
    productType: 'physical',
    contactEmail: 'contato@lojaexemplo.com.br',
    productDescription: 'Roupas e acessórios femininos',
    address: {
      addressLine1: 'Av. Paulista, 1000',
      neighborhood: 'Bela Vista',
      city: 'São Paulo',
      state: 'SP',
      country: 'BRA',
      postalCode: '01310100',
    },
    phones: [{ type: 'mobile', number: '+5511987654321' }],
    legalRepresentative: {
      fullName: 'Ana Lima',
      dateOfBirth: '1988-04-12',
      nationality: 'Brasileira',
      idNumber: '52998224725',
      email: 'ana.lima@email.com',
      motherName: 'Maria Lima',
      gender: 'F',
      phones: [{ type: 'mobile', number: '+5511987654321' }],
    },
    bankAccount: {
      bankCode: '001',
      agencyCode: '1234',
      accountNumber: '567890',
      accountDigit: '0',
      accountType: 'checking',
      bankName: 'Banco do Brasil',
      recipientName: 'LOJA EXEMPLO LTDA',
      recipientDocument: '11222333000181',
    },
    canAccessDashboard: false,
  }),
});

const result = await response.json();

if (response.status === 201) {
  // Guarde result.id e os ids de result.legalRepresentatives
  console.log(result.id, result.legalRepresentatives);
} else if (response.status === 409) {
  // CNPJ já cadastrado: procure a subconta existente em vez de criar outra
} else {
  console.error(response.status, result.message);
}
```

```python Python theme={null}
import os

import requests

payload = {
    "legalName": "LOJA EXEMPLO LTDA",
    "tradeName": "Loja Exemplo",
    "companyTaxId": "11.222.333/0001-81",
    "website": "https://loja.exemplo.com.br",
    "averageMonthlyRevenue": 30000,
    "averageOrderValue": 150,
    "productType": "physical",
    "contactEmail": "contato@lojaexemplo.com.br",
    "productDescription": "Roupas e acessórios femininos",
    "softDescriptor": "LOJAEXEMPLO",
    "address": {
        "addressLine1": "Av. Paulista, 1000",
        "addressLine2": "Sala 12",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA",
        "postalCode": "01310100",
    },
    "phones": [
        {
            "type": "mobile",
            "number": "+5511987654321",
        },
    ],
    "legalRepresentative": {
        "fullName": "Ana Lima",
        "dateOfBirth": "1988-04-12",
        "nationality": "Brasileira",
        "idNumber": "52998224725",
        "issuingCountry": "BRA",
        "email": "ana.lima@email.com",
        "motherName": "Maria Lima",
        "gender": "F",
        "phones": [
            {
                "type": "mobile",
                "number": "+5511987654321",
            },
        ],
    },
    "additionalRepresentatives": [
        {
            "fullName": "Joao Silva",
            "dateOfBirth": "1985-05-10",
            "nationality": "Brasileira",
            "idNumber": "11144477735",
            "issuingCountry": "BRA",
            "email": "joao.silva@email.com",
            "motherName": "Joana Silva",
            "gender": "M",
            "phones": [
                {
                    "type": "mobile",
                    "number": "+5511987654321",
                },
            ],
        },
    ],
    "bankAccount": {
        "bankCode": "001",
        "agencyCode": "1234",
        "accountNumber": "567890",
        "accountDigit": "0",
        "accountType": "checking",
        "bankName": "Banco do Brasil",
        "recipientName": "LOJA EXEMPLO LTDA",
        "recipientDocument": "11222333000181",
    },
    "canAccessDashboard": True,
    "user": {
        "fullName": "Ana Lima",
        "email": "ana.lima@email.com",
        "phone": "+5511987654321",
    },
    "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/submerchants",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$payload = [
    'legalName' => 'LOJA EXEMPLO LTDA',
    'tradeName' => 'Loja Exemplo',
    'companyTaxId' => '11.222.333/0001-81',
    'website' => 'https://loja.exemplo.com.br',
    'averageMonthlyRevenue' => 30000,
    'averageOrderValue' => 150,
    'productType' => 'physical',
    'contactEmail' => 'contato@lojaexemplo.com.br',
    'productDescription' => 'Roupas e acessórios femininos',
    'softDescriptor' => 'LOJAEXEMPLO',
    'address' => [
        'addressLine1' => 'Av. Paulista, 1000',
        'addressLine2' => 'Sala 12',
        'neighborhood' => 'Bela Vista',
        'city' => 'São Paulo',
        'state' => 'SP',
        'country' => 'BRA',
        'postalCode' => '01310100',
    ],
    'phones' => [
        [
            'type' => 'mobile',
            'number' => '+5511987654321',
        ],
    ],
    'legalRepresentative' => [
        'fullName' => 'Ana Lima',
        'dateOfBirth' => '1988-04-12',
        'nationality' => 'Brasileira',
        'idNumber' => '52998224725',
        'issuingCountry' => 'BRA',
        'email' => 'ana.lima@email.com',
        'motherName' => 'Maria Lima',
        'gender' => 'F',
        'phones' => [
            [
                'type' => 'mobile',
                'number' => '+5511987654321',
            ],
        ],
    ],
    'additionalRepresentatives' => [
        [
            'fullName' => 'Joao Silva',
            'dateOfBirth' => '1985-05-10',
            'nationality' => 'Brasileira',
            'idNumber' => '11144477735',
            'issuingCountry' => 'BRA',
            'email' => 'joao.silva@email.com',
            'motherName' => 'Joana Silva',
            'gender' => 'M',
            'phones' => [
                [
                    'type' => 'mobile',
                    'number' => '+5511987654321',
                ],
            ],
        ],
    ],
    'bankAccount' => [
        'bankCode' => '001',
        'agencyCode' => '1234',
        'accountNumber' => '567890',
        'accountDigit' => '0',
        'accountType' => 'checking',
        'bankName' => 'Banco do Brasil',
        'recipientName' => 'LOJA EXEMPLO LTDA',
        'recipientDocument' => '11222333000181',
    ],
    'canAccessDashboard' => true,
    'user' => [
        'fullName' => 'Ana Lima',
        'email' => 'ana.lima@email.com',
        'phone' => '+5511987654321',
    ],
    'postbackUrl' => 'https://meusite.com.br/webhooks/finvia/conta',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String payload = """
            {
              "legalName": "LOJA EXEMPLO LTDA",
              "tradeName": "Loja Exemplo",
              "companyTaxId": "11.222.333/0001-81",
              "website": "https://loja.exemplo.com.br",
              "averageMonthlyRevenue": 30000,
              "averageOrderValue": 150,
              "productType": "physical",
              "contactEmail": "contato@lojaexemplo.com.br",
              "productDescription": "Roupas e acessórios femininos",
              "softDescriptor": "LOJAEXEMPLO",
              "address": {
                "addressLine1": "Av. Paulista, 1000",
                "addressLine2": "Sala 12",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "state": "SP",
                "country": "BRA",
                "postalCode": "01310100"
              },
              "phones": [
                {
                  "type": "mobile",
                  "number": "+5511987654321"
                }
              ],
              "legalRepresentative": {
                "fullName": "Ana Lima",
                "dateOfBirth": "1988-04-12",
                "nationality": "Brasileira",
                "idNumber": "52998224725",
                "issuingCountry": "BRA",
                "email": "ana.lima@email.com",
                "motherName": "Maria Lima",
                "gender": "F",
                "phones": [
                  {
                    "type": "mobile",
                    "number": "+5511987654321"
                  }
                ]
              },
              "additionalRepresentatives": [
                {
                  "fullName": "Joao Silva",
                  "dateOfBirth": "1985-05-10",
                  "nationality": "Brasileira",
                  "idNumber": "11144477735",
                  "issuingCountry": "BRA",
                  "email": "joao.silva@email.com",
                  "motherName": "Joana Silva",
                  "gender": "M",
                  "phones": [
                    {
                      "type": "mobile",
                      "number": "+5511987654321"
                    }
                  ]
                }
              ],
              "bankAccount": {
                "bankCode": "001",
                "agencyCode": "1234",
                "accountNumber": "567890",
                "accountDigit": "0",
                "accountType": "checking",
                "bankName": "Banco do Brasil",
                "recipientName": "LOJA EXEMPLO LTDA",
                "recipientDocument": "11222333000181"
              },
              "canAccessDashboard": true,
              "user": {
                "fullName": "Ana Lima",
                "email": "ana.lima@email.com",
                "phone": "+5511987654321"
              },
              "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var payload = """
{
  "legalName": "LOJA EXEMPLO LTDA",
  "tradeName": "Loja Exemplo",
  "companyTaxId": "11.222.333/0001-81",
  "website": "https://loja.exemplo.com.br",
  "averageMonthlyRevenue": 30000,
  "averageOrderValue": 150,
  "productType": "physical",
  "contactEmail": "contato@lojaexemplo.com.br",
  "productDescription": "Roupas e acessórios femininos",
  "softDescriptor": "LOJAEXEMPLO",
  "address": {
    "addressLine1": "Av. Paulista, 1000",
    "addressLine2": "Sala 12",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "country": "BRA",
    "postalCode": "01310100"
  },
  "phones": [
    {
      "type": "mobile",
      "number": "+5511987654321"
    }
  ],
  "legalRepresentative": {
    "fullName": "Ana Lima",
    "dateOfBirth": "1988-04-12",
    "nationality": "Brasileira",
    "idNumber": "52998224725",
    "issuingCountry": "BRA",
    "email": "ana.lima@email.com",
    "motherName": "Maria Lima",
    "gender": "F",
    "phones": [
      {
        "type": "mobile",
        "number": "+5511987654321"
      }
    ]
  },
  "additionalRepresentatives": [
    {
      "fullName": "Joao Silva",
      "dateOfBirth": "1985-05-10",
      "nationality": "Brasileira",
      "idNumber": "11144477735",
      "issuingCountry": "BRA",
      "email": "joao.silva@email.com",
      "motherName": "Joana Silva",
      "gender": "M",
      "phones": [
        {
          "type": "mobile",
          "number": "+5511987654321"
        }
      ]
    }
  ],
  "bankAccount": {
    "bankCode": "001",
    "agencyCode": "1234",
    "accountNumber": "567890",
    "accountDigit": "0",
    "accountType": "checking",
    "bankName": "Banco do Brasil",
    "recipientName": "LOJA EXEMPLO LTDA",
    "recipientDocument": "11222333000181"
  },
  "canAccessDashboard": true,
  "user": {
    "fullName": "Ana Lima",
    "email": "ana.lima@email.com",
    "phone": "+5511987654321"
  },
  "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "legalName": "LOJA EXEMPLO LTDA",
	  "tradeName": "Loja Exemplo",
	  "companyTaxId": "11.222.333/0001-81",
	  "website": "https://loja.exemplo.com.br",
	  "averageMonthlyRevenue": 30000,
	  "averageOrderValue": 150,
	  "productType": "physical",
	  "contactEmail": "contato@lojaexemplo.com.br",
	  "productDescription": "Roupas e acessórios femininos",
	  "softDescriptor": "LOJAEXEMPLO",
	  "address": {
	    "addressLine1": "Av. Paulista, 1000",
	    "addressLine2": "Sala 12",
	    "neighborhood": "Bela Vista",
	    "city": "São Paulo",
	    "state": "SP",
	    "country": "BRA",
	    "postalCode": "01310100"
	  },
	  "phones": [
	    {
	      "type": "mobile",
	      "number": "+5511987654321"
	    }
	  ],
	  "legalRepresentative": {
	    "fullName": "Ana Lima",
	    "dateOfBirth": "1988-04-12",
	    "nationality": "Brasileira",
	    "idNumber": "52998224725",
	    "issuingCountry": "BRA",
	    "email": "ana.lima@email.com",
	    "motherName": "Maria Lima",
	    "gender": "F",
	    "phones": [
	      {
	        "type": "mobile",
	        "number": "+5511987654321"
	      }
	    ]
	  },
	  "additionalRepresentatives": [
	    {
	      "fullName": "Joao Silva",
	      "dateOfBirth": "1985-05-10",
	      "nationality": "Brasileira",
	      "idNumber": "11144477735",
	      "issuingCountry": "BRA",
	      "email": "joao.silva@email.com",
	      "motherName": "Joana Silva",
	      "gender": "M",
	      "phones": [
	        {
	          "type": "mobile",
	          "number": "+5511987654321"
	        }
	      ]
	    }
	  ],
	  "bankAccount": {
	    "bankCode": "001",
	    "agencyCode": "1234",
	    "accountNumber": "567890",
	    "accountDigit": "0",
	    "accountType": "checking",
	    "bankName": "Banco do Brasil",
	    "recipientName": "LOJA EXEMPLO LTDA",
	    "recipientDocument": "11222333000181"
	  },
	  "canAccessDashboard": true,
	  "user": {
	    "fullName": "Ana Lima",
	    "email": "ana.lima@email.com",
	    "phone": "+5511987654321"
	  },
	  "postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "legalName" => "LOJA EXEMPLO LTDA",
  "tradeName" => "Loja Exemplo",
  "companyTaxId" => "11.222.333/0001-81",
  "website" => "https://loja.exemplo.com.br",
  "averageMonthlyRevenue" => 30000,
  "averageOrderValue" => 150,
  "productType" => "physical",
  "contactEmail" => "contato@lojaexemplo.com.br",
  "productDescription" => "Roupas e acessórios femininos",
  "softDescriptor" => "LOJAEXEMPLO",
  "address" => {
    "addressLine1" => "Av. Paulista, 1000",
    "addressLine2" => "Sala 12",
    "neighborhood" => "Bela Vista",
    "city" => "São Paulo",
    "state" => "SP",
    "country" => "BRA",
    "postalCode" => "01310100",
  },
  "phones" => [
    {
      "type" => "mobile",
      "number" => "+5511987654321",
    },
  ],
  "legalRepresentative" => {
    "fullName" => "Ana Lima",
    "dateOfBirth" => "1988-04-12",
    "nationality" => "Brasileira",
    "idNumber" => "52998224725",
    "issuingCountry" => "BRA",
    "email" => "ana.lima@email.com",
    "motherName" => "Maria Lima",
    "gender" => "F",
    "phones" => [
      {
        "type" => "mobile",
        "number" => "+5511987654321",
      },
    ],
  },
  "additionalRepresentatives" => [
    {
      "fullName" => "Joao Silva",
      "dateOfBirth" => "1985-05-10",
      "nationality" => "Brasileira",
      "idNumber" => "11144477735",
      "issuingCountry" => "BRA",
      "email" => "joao.silva@email.com",
      "motherName" => "Joana Silva",
      "gender" => "M",
      "phones" => [
        {
          "type" => "mobile",
          "number" => "+5511987654321",
        },
      ],
    },
  ],
  "bankAccount" => {
    "bankCode" => "001",
    "agencyCode" => "1234",
    "accountNumber" => "567890",
    "accountDigit" => "0",
    "accountType" => "checking",
    "bankName" => "Banco do Brasil",
    "recipientName" => "LOJA EXEMPLO LTDA",
    "recipientDocument" => "11222333000181",
  },
  "canAccessDashboard" => true,
  "user" => {
    "fullName" => "Ana Lima",
    "email" => "ana.lima@email.com",
    "phone" => "+5511987654321",
  },
  "postbackUrl" => "https://meusite.com.br/webhooks/finvia/conta",
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 201 theme={null}
{
  "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "legalRepresentatives": [
    {
      "id": "2vorkEaaaBbbCccDddEeeFffGgg",
      "fullName": "Ana Lima",
      "isPrimary": true
    },
    {
      "id": "2vorkEbbbCccDddEeeFffGggHhh",
      "fullName": "Joao Silva",
      "isPrimary": false
    }
  ]
}
```

```json 400 theme={null}
{
  "statusCode": 400,
  "message": ["address.country must be a valid ISO31661 Alpha3 code"],
  "error": "Bad Request"
}
```

```json 403 theme={null}
{ "statusCode": 403, "message": "Fast Connect not enabled." }
```

```json 409 theme={null}
{
  "statusCode": 409,
  "message": "Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.",
  "error": "Conflict"
}
```

## Veja também

> [card] [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
>
> Cadastro e credenciamento passo a passo.

> [card] [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md)
>
> Documentos exigidos, motivos de recusa e MCCs não aceitos.

> [card] [Sócios e documentos](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md)
>
> Documentos de cada sócio com token de upload.

> [card] [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md)
>
> Avisos de mudança de status.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.