> ## 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.

# Connect: visão geral

> Crie e gerencie subcontas vinculadas à sua conta, divida o valor das vendas entre elas e permita que cada uma saque o próprio saldo.

O Connect é o módulo da Finvia para quem precisa operar várias contas de recebimento debaixo de uma conta master: marketplaces, plataformas de venda e PSPs (provedores de serviços de pagamento) parceiros que cadastram seus lojistas como subcontas. Com ele, a sua empresa cria **subcontas** para os vendedores ou clientes dela, controla taxas, permissões e acessos de cada uma, divide o valor das vendas entre as contas (split) e acompanha tudo com rastreabilidade por transação.

> [!NOTE]
>
> As rotas e algumas mensagens da API ainda usam o nome anterior do módulo, como `/v1/fast-connect/...` e `Fast Connect not enabled.`. Eles aparecem nesta documentação exatamente como a API devolve.

## Quando usar

| Situação | O Connect resolve? |
| - | - |
| Marketplace com vários vendedores, em que cada venda precisa ficar registrada no vendedor certo | Sim. Cada vendedor vira uma subconta e cobra com as próprias chaves |
| Plataforma (SaaS, loja virtual, infoprodutos) que cobra comissão sobre as vendas dos clientes | Sim. A comissão é separada automaticamente por split em cada venda |
| PSP parceiro que cadastra seus lojistas como subcontas e precisa de cadastro, análise documental (KYC) e saque por lojista | Sim. Cadastro, documentos, status de aprovação e saque ficam na API |
| Empresa com um único CNPJ que só vende os próprios produtos | Não precisa. Use a conta normal e a [cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md) sem split |
| Dividir uma venda com empresas que não estão no seu [grupo Connect](https://docs.fastpaybrasil.com/glossario.md) (a conta master e as subcontas dela) | Não. Todas as contas do split precisam pertencer ao mesmo grupo |

> [!NOTE]
>
> **Para o negócio:** o Connect não é liberado automaticamente. O módulo precisa ser habilitado pela Finvia na sua conta. Fale com o time comercial ou de suporte para pedir a liberação antes de começar a integração. PSPs e plataformas que usam o Connect seguem as [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md): split obrigatório em toda transação de PSP, pré-validação do lojista, documentos exigidos e ramos não aceitos.

## Conta master e subconta

O Connect trabalha com dois papéis:

| Papel | Quem é | O que pode fazer |
| - | - | - |
| **Conta master** (MerchantMaster) | A sua empresa, liberada pela Finvia para usar o módulo | Criar subcontas, enviar e consultar documentos, listar subcontas e sócios, obter as chaves de cada subconta, consultar as taxas de cada subconta, receber parte das vendas por split e originar vendas com split para subcontas |
| **Subconta** (SubMerchant) | Cada vendedor, lojista ou cliente que você cadastra | Depois de aprovada, criar cobranças com as próprias chaves, dividir vendas com a master ou com outras subcontas do grupo, consultar as próprias taxas e solicitar saque do próprio saldo |

Na criação, a subconta recebe uma **cópia das taxas, permissões e configurações vigentes da conta master**. Ela nasce com as condições comerciais que a Finvia definiu para a sua conta, e você não precisa configurar taxa por taxa a cada cadastro. Depois disso, as taxas da subconta são independentes: mudar as taxas da master não altera as das subcontas já criadas.

O desenho abaixo mostra a estrutura de um grupo Connect: a master, as subcontas que ela cria e o que cada subconta recebe.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    FIN["Finvia<br/>habilita o Connect"]:::finvia
    M["Conta master<br/>sua empresa, PSP<br/>ou plataforma"]:::lojista
    S1["Subconta 1<br/>vendedor ou lojista"]:::lojista
    S2["Subconta 2<br/>vendedor ou lojista"]:::lojista
    S3["Subconta N<br/>vendedor ou lojista"]:::lojista
    OWN["Com status active:<br/>chaves de API próprias,<br/>vendas, saldo e saque"]:::ok
    FIN ==>|"1. libera o módulo"| M
    M -->|"2. cria com cópia das taxas,<br/>permissões e configurações"| S2
    M --> S1
    M --> S3
    S1 -.-> OWN
    S2 -.-> OWN
    S3 -.-> OWN
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

O split pode ir da master para uma subconta, de uma subconta para a master ou entre duas subcontas do mesmo grupo (veja [Relações de split permitidas](#relações-de-split-permitidas)). A subconta só usa as chaves, vende e saca depois de aprovada (`active`).

> [!NOTE]
>
> A rota [`GET /v1/fast-connect/sub-accounts/{id}/fees-info`](https://docs.fastpaybrasil.com/referencia/fast-connect/taxas-e-dados) devolve as taxas efetivas da subconta. Se `fees` vier vazio, as cobranças dela são recusadas até a Finvia configurar as taxas. Veja [Taxas da subconta](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md).

## Como funciona

**1. Liberação do módulo**

A Finvia habilita o Connect na sua conta, que passa a ser uma conta master.

**2. Cadastro da subconta**

Você cria a subconta com `POST /v1/submerchants`, enviando dados da empresa, do representante legal, dos sócios (se houver) e da conta bancária. A subconta nasce com status `pending`.

**3. Documentos e análise (KYC)**

Você envia os documentos da empresa e das pessoas. A Finvia analisa o cadastro (KYC, a verificação de identidade e de dados da empresa) e o status muda para `pre_approved`, `correcting`, `active` ou `rejected`. Detalhes em [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md) e [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md).

**4. Chaves da subconta**

Com a subconta `active`, você obtém as chaves de API dela em `GET /v1/submerchants/{id}/api-keys`.

**5. Vendas com split**

A subconta cria cobranças com a chave dela, e o valor pode ser dividido com a master ou com outras subcontas. Veja [Split de pagamentos](https://docs.fastpaybrasil.com/guias/fast-connect/split.md).

**6. Liquidação e saque**

Cada parte do split é repassada parcela a parcela, quando o recebível do originador é [liquidado](https://docs.fastpaybrasil.com/glossario.md): no cartão, a cada 30 dias por parcela (D+30, D+60...); no Pix, logo após a confirmação do pagamento. O valor entra no saldo disponível de quem recebe. O saque da subconta vai por Pix para a chave CNPJ dela. Veja [Split de pagamentos](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) e [Saques da subconta](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md).

O desenho abaixo mostra o caminho do dinheiro em uma venda com split, do pagamento ao saque da subconta.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    C(["Comprador"]):::comprador
    COB["Cobrança com a chave<br/>da subconta originadora<br/>POST /v1/charges com split"]:::lojista
    API["Finvia API<br/>desconta as taxas"]:::finvia
    LIQ["Liquidação por parcela<br/>cartão: D+30, D+60...<br/>Pix: após a confirmação"]:::alerta
    REC["Saldo de quem recebe<br/>o split: master ou<br/>outra subconta do grupo"]:::ok
    ORI["Saldo da subconta<br/>originadora: o que<br/>não foi dividido"]:::ok
    SAQ["Saque da subconta<br/>POST .../payout-requests<br/>com a chave da master"]:::lojista
    BAN["Pix em BRL para a<br/>chave CNPJ da subconta"]:::externo
    C -->|"1. paga"| COB
    COB -->|"2. envia"| API
    API -->|"3. valor líquido"| LIQ
    LIQ -->|"4. % do split"| REC
    LIQ -->|"4. restante"| ORI
    ORI -->|"5. pede o saque"| SAQ
    SAQ -->|"6. aprovação manual<br/>da operação Finvia"| BAN
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
```

Quem recebe o split também tem a parte dele liberada parcela a parcela, no mesmo ritmo da liquidação do originador. As regras de cada etapa estão em [Split de pagamentos](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) e [Saques da subconta](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md).

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Liberação | O módulo é habilitado pela Finvia. Sem a liberação, rotas como a de taxas (`fees-info`) e a de saque respondem `403` |
| Cópia de taxas | Na criação, a subconta recebe uma cópia das taxas, permissões e configurações da master. Depois, as taxas são independentes |
| Aprovação | A subconta só pode transacionar depois de aprovada (status `active`) |
| Chaves | As chaves de cada subconta são obtidas pela master em `GET /v1/submerchants/{id}/api-keys` |
| Split | A soma dos percentuais não pode passar de 100%. O que não for dividido fica com o [originador](https://docs.fastpaybrasil.com/glossario.md), a conta que criou a cobrança |
| Split em PSP | Toda transação de PSP precisa ter split entre a conta master (PSP) e a subconta (lojista). Split de 100% para o PSP não é permitido |
| Grupo | Todas as contas de um split precisam pertencer ao mesmo grupo Connect |
| Base do split | O percentual é aplicado sobre o [valor líquido](https://docs.fastpaybrasil.com/glossario.md), depois das taxas da Finvia |
| Saque da subconta | Sempre em BRL, via Pix, para a chave Pix CNPJ da subconta, com aprovação manual da operação Finvia |

### Relações de split permitidas

| Quem origina a venda | Quem pode receber parte dela |
| - | - |
| Conta master | Subconta |
| Subconta | Conta master |
| Subconta | Outra subconta do mesmo grupo |

> [!WARNING]
>
> Para que a venda fique vinculada à subconta que vendeu, a cobrança precisa ser criada com a **chave secreta da subconta originadora**, obtida em `GET /v1/submerchants/{id}/api-keys`. É a chave usada na chamada que define quem originou a venda.

## Qual chave usar em cada chamada

| Operação | Rota | Autenticação |
| - | - | - |
| Criar subconta | `POST /v1/submerchants` | Basic, chave secreta da master |
| Listar subcontas | `GET /v1/submerchants` | Basic, chave secreta da master |
| Consultar subconta | `GET /v1/submerchants/{id}` | Basic, chave secreta da master |
| Enviar documentos (direto) | `POST /v1/submerchants/{id}/document` | Basic, chave secreta da master |
| Emitir token de upload | `POST /v1/submerchants/{merchantId}/document/upload-token` | Basic, chave secreta da master |
| Enviar documentos com token | `POST /v1/document-uploads` | Bearer, com o **token de upload** (não é a chave de API) |
| Listar sócios e documentos | `GET /v1/submerchants/{merchantId}/legal-representatives` | Basic, chave secreta da master |
| Obter as chaves da subconta | `GET /v1/submerchants/{id}/api-keys` | Basic, chave secreta da master |
| Consultar taxas e dados cadastrais | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | Basic, chave secreta da master ou da subconta |
| Criar cobrança com split | `POST /v1/charges` | Basic, chave secreta de quem **origina** a venda (normalmente a subconta) |
| Solicitar saque da subconta | `POST /v1/submerchants/{merchantId}/payout-requests` | Basic, chave secreta da master |
| Listar saques | `GET /v1/payout-requests` | Basic, chave secreta da master |

> [!NOTE]
>
> Nas rotas de saque e de saldo, a chave age com as permissões do usuário que a gerou: uma chave de usuário com perfil **Desenvolvedor** recebe `403` `Acesso negado`. Com a chave de teste, a criação de saque responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`, porque não existe saque no Modo Teste.

> [!TIP]
>
> **Para o desenvolvedor:** guarde as chaves de cada subconta no seu cofre de segredos, associadas ao `id` da subconta. Na hora de criar a cobrança, a sua aplicação escolhe a chave pela subconta que está vendendo. A chave secreta da subconta segue as mesmas regras da sua: nunca vai para o navegador nem para o aplicativo.

## Mapa das rotas

| Grupo | Rota | Página |
| - | - | - |
| Subcontas | `POST /v1/submerchants` | [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md) |
| Subcontas | `GET /v1/submerchants` | [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md) |
| Subcontas | `GET /v1/submerchants/{id}` | [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md) |
| Documentos | `POST /v1/submerchants/{id}/document` | [Enviar documentos](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos.md) |
| Documentos | `POST /v1/submerchants/{merchantId}/document/upload-token` | [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md) |
| Documentos | `POST /v1/document-uploads` | [Enviar documentos com token](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token.md) |
| Sócios | `GET /v1/submerchants/{merchantId}/legal-representatives` | [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md) |
| Chaves | `GET /v1/submerchants/{id}/api-keys` | [Chaves de API](https://docs.fastpaybrasil.com/referencia/fast-connect/chaves-de-api.md) |
| Taxas | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | [Taxas e dados](https://docs.fastpaybrasil.com/referencia/fast-connect/taxas-e-dados.md) |
| Saques | `POST /v1/submerchants/{merchantId}/payout-requests` | [Criar saque da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque.md) |
| Saques | `GET /v1/payout-requests` | [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) |
| Cobranças | `POST /v1/charges` (campo `split`) | [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md) |

## Passo a passo resumido

Um primeiro contato com o módulo, depois da liberação. Os detalhes de cada etapa estão nas páginas seguintes.

```bash 1. Criar a subconta (chave da master) theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d @subconta.json
```

```bash 2. Consultar o status (chave da master) theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI" \
  -u "$FINVIA_API_KEY:"
```

```bash 3. Obter as chaves (subconta active) theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkDcXyvzifL63YX09S9VqcnI/api-keys" \
  -u "$FINVIA_API_KEY:"
```

```bash 4. Vender com split (chave da subconta) theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$SUBCONTA_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "BRL",
    "customer": { "name": "Ana Lima", "email": "ana@email.com" },
    "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 },
    "items": [
      { "title": "Aula de cerâmica online", "type": "digital", "description": "Turma de sábado", "unit_price": 100, "quantity": 1 }
    ],
    "split": [
      { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 10 }
    ]
  }'
```

No passo 4, `36OO3bcGjhPjjF3tzrqOGcmQuKo` representa o `id` da conta que recebe a comissão (por exemplo, a master).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `403` com "Connect não habilitado para esta conta" ou "Connect not enabled." | Módulo não habilitado na sua conta | Peça à Finvia a liberação do Connect |
| `404` ao buscar as chaves da subconta | A subconta não tem chaves ou não pertence à master | Confira o `id` e o status da subconta |
| Cadastro de lojista recusado | Documento inválido, ramo não aceito, empresa inapta, entre outros | Veja os motivos em [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md) |
| Venda não aparece vinculada à subconta | Cobrança criada com a chave da master | Crie a cobrança com a chave secreta da subconta originadora |
| Comissão recebida menor que a esperada | O percentual do split incide sobre o líquido, depois das taxas | Ajuste o percentual com a fórmula de [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) |
| `404` em rotas de subconta | A subconta não pertence à master autenticada | Confira o `id` e a chave usada |

## Perguntas frequentes

> [accordion] Como peço a liberação do Connect?
>
> Pelo seu contato comercial ou pelo suporte da Finvia. O módulo é instalado e habilitado pela Finvia na sua conta, que passa a funcionar como conta master.

> [accordion] Preciso configurar as taxas de cada subconta?
>
> Não na criação. A subconta recebe uma cópia das taxas, permissões e configurações da master no momento em que é criada. Depois disso, as taxas dela são independentes. Para conferir as taxas de uma subconta, use a rota de [taxas e dados](https://docs.fastpaybrasil.com/referencia/fast-connect/taxas-e-dados.md). Se `fees` vier vazio, fale com o suporte: as cobranças dessa subconta são recusadas até a configuração.

> [accordion] A subconta pode vender antes de ser aprovada?
>
> Não. A subconta só fica apta a transacionar com status `active`.

> [accordion] A subconta pode acessar o painel da Finvia?
>
> Pode, se você quiser. Na criação, o campo `canAccessDashboard` define o acesso. Quando ele é `true`, você informa também o objeto `user` com nome, e-mail e telefone do usuário que vai entrar no painel.

> [accordion] Posso dividir uma venda entre duas subcontas sem passar pela master?
>
> Sim. A relação subconta para subconta é permitida, desde que as duas pertençam ao mesmo grupo Connect.

## Como testar

A homologação do Connect está no [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md):

* **FC-01 a FC-08**: criação da subconta, envio de documentos, consulta até `active`, obtenção das chaves, cobrança com a chave da subconta, cobrança com split, saque da subconta e recebimento do aviso de mudança de status.
* **SPL-01 a SPL-06**: cobranças com split, validações e conferência dos valores.

Use as chaves de teste (`sk_test_`) da master. As chaves de subconta em modo de teste também vêm com prefixo `sk_test_` e `pk_test_`. O saque (FC-07) não existe no Modo Teste: com chave de teste, a resposta é `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. Veja no roteiro como esse cenário é conferido.

## Veja também

> [card] [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
>
> Cadastro, documentos e status de aprovação.

> [card] [Split de pagamentos](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)
>
> Regras e exemplos de divisão de vendas.

> [card] [Saques da subconta](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md)
>
> Como a subconta retira o saldo via Pix.

> [card] [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md)
>
> Regras para PSPs e plataformas, documentos e MCCs não aceitos.

> [card] [Marketplace e PSP](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md)
>
> Caso de uso completo com subcontas e split.


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