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

# Marketplace e PSP

> Plataforma com vários vendedores: subcontas com KYC, split com comissão calculada sobre o valor bruto, prazos de repasse, saques dos vendedores e avisos de conta e de saque.

Um marketplace vende produtos de muitos lojistas em um só lugar. Cada venda pertence ao lojista, e a plataforma fica com uma comissão. Para isso funcionar, cada lojista precisa de uma conta própria, com cadastro e análise de documentos, e cada venda precisa separar a comissão da plataforma no momento do pagamento. Esta página mostra como montar esse modelo com o módulo Connect da Finvia e, no fim, como a mesma estrutura atende um PSP (provedor de serviços de pagamento) parceiro que cadastra seus lojistas como subcontas.

> [!TIP]
>
> Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](https://docs.fastpaybrasil.com/integrar-com-ia.md).

Implementar este caso com um assistente de IA

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/saque.md](https://docs.fastpaybrasil.com/guias/webhooks/saque.md)
* [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar neste projeto o fluxo descrito na página "Marketplace e PSP" ([https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md)). Resumo do caso: Plataforma com vários vendedores: subcontas com KYC, split com comissão calculada sobre o valor bruto, prazos de repasse, saques dos vendedores e avisos de conta e de saque.

Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

## O cenário

A **Feira Online** é um marketplace de produtos artesanais com **300 lojistas**: ceramistas, marceneiros, tecelãs, joalheiros. Cada lojista vende pelo site da Feira, recebe o dinheiro na própria conta e paga à plataforma uma comissão de **2% sobre o valor bruto** de cada venda.

Os números da operação:

| Indicador | Valor |
| - | - |
| Lojistas ativos | 300 |
| Pedidos por mês | 6.500 |
| Ticket médio | R\$ 100 |
| Formas de pagamento | Pix e cartão em até 6x |
| Comissão da plataforma | 2% sobre o valor bruto |

## O que a Finvia resolve

> [!NOTE]
>
> **Para o negócio:** com o Connect, a Feira Online vira a conta master (MerchantMaster) e cada lojista ganha uma subconta (SubMerchant) vinculada a ela, com taxas, permissões e rastreabilidade próprias. Cada lojista passa pela análise de documentos (KYC, a verificação de identidade da empresa e dos sócios). Cada venda é criada na subconta do lojista, e o campo `split` define a parte da plataforma. O valor de cada participante é calculado na criação da cobrança e repassado a cada parcela, quando o recebível do lojista é [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 lojista saca o próprio saldo por Pix para a chave CNPJ dele.

## Arquitetura da solução

| Etapa | O que acontece | Rota |
| - | - | - |
| 1. Liberação | A Finvia habilita o módulo Connect na conta da Feira Online | Contato com o time Finvia |
| 2. Cadastro do lojista | A Feira cria a subconta com dados da empresa, representante legal e conta bancária | `POST /v1/submerchants` |
| 3. KYC | Envio de cartão CNPJ, contrato social, documento do responsável e selfie | `POST /v1/submerchants/{merchantId}/document` |
| 4. Sócios adicionais | Documentos de cada sócio pelo fluxo com token | `POST /v1/submerchants/{merchantId}/document/upload-token` e `POST /v1/document-uploads` |
| 5. Aprovação | A Feira acompanha o status até `active` | `GET /v1/submerchants/{merchantId}` e aviso de status de conta |
| 6. Chaves do lojista | A Feira obtém as chaves da subconta ativa | `GET /v1/submerchants/{merchantId}/api-keys` |
| 7. Taxas | A Feira consulta as taxas da subconta para calcular o split | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` |
| 8. Vendas com split | Cada venda é criada com a chave da subconta e a comissão em `split` | `POST /v1/charges` |
| 9. Conferência | A Feira confere o split de cada venda | `GET /v1/charges/{id}` (campo `splits`) |
| 10. Saque | O lojista saca o saldo via Pix para a chave CNPJ | `POST /v1/submerchants/{merchantId}/payout-requests` |
| 11. Acompanhamento | Listagem de saques e avisos de saque | `GET /v1/payout-requests` e [Webhooks de saque](https://docs.fastpaybrasil.com/guias/webhooks/saque.md) |

O desenho abaixo mostra a ordem das chamadas, do cadastro do lojista à primeira venda com split.

```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}}}%%

sequenceDiagram
    autonumber
    box rgb(255,246,229) Lojista e comprador
        participant L as Lojista
        participant C as Comprador
    end
    box rgb(243,245,248) Sua aplicação
        participant M as Feira Online
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant A as Adquirente
    end
    L->>M: Dados da empresa, sócios e documentos
    M->>F: POST /v1/submerchants
    F-->>M: 201 · id · subconta em pending
    M->>F: POST .../{merchantId}/document
    Note over F: Análise do cadastro em até 24 h, em média
    F-)M: pre_approved, depois active · URL de aviso de status
    M->>F: GET .../{merchantId}/api-keys
    F-->>M: secretKey da subconta
    M->>F: GET .../sub-accounts/{id}/fees-info
    C->>M: Compra um vaso de R$ 100
    M->>F: POST /v1/charges com split
    F->>A: Autoriza o cartão
    F-->>M: 201 · paid
    F-)M: charge.paid · merchant_id
```

Depois da venda, o dinheiro segue o caminho abaixo. Os valores são os do exemplo desta página: venda de R\$ 100,00 no cartão em 2x, com taxa de 5% e R\$ 0,40 fixos.

```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 paga R$ 100<br/>no cartão em 2x"]):::comprador
    V["Venda na subconta<br/>do Ateliê Barro Fino"]:::finvia
    AL["Saldo a liberar<br/>do lojista · R$ 94,60<br/>líquido da taxa"]:::alerta
    LQ["Liquidação da parcela<br/>D+30 e D+60"]:::finvia
    FE["Saldo disponível<br/>da Feira Online<br/>R$ 1,00 por parcela"]:::ok
    LD["Saldo disponível<br/>do lojista<br/>R$ 46,30 por parcela"]:::ok
    SQ["Saque pending<br/>valor reservado"]:::alerta
    AP{"Finvia<br/>aprova?"}:::decisao
    BC["Conta do Ateliê<br/>Pix na chave CNPJ<br/>recebe netAmount"]:::externo
    RJ["rejected<br/>valor volta ao saldo"]:::erro
    C ==>|"1. POST /v1/charges<br/>com split"| V
    V -->|"2. fica a liberar"| AL
    AL -->|"3. cada parcela<br/>a cada 30 dias"| LQ
    V -.->|"no Pix: no mesmo dia,<br/>após a confirmação"| LQ
    LQ -->|"4. 2,1142% do líquido"| FE
    LQ -->|"4. o restante"| LD
    LD -->|"5. POST .../payout-requests<br/>chave da conta master"| SQ
    SQ --> AP
    AP ==>|"approved<br/>payout.approved"| BC
    AP -->|"payout.rejected"| RJ
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    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
```

No Pix, o repasse acontece no mesmo dia, logo após a confirmação do pagamento. O saque desconta a `payoutFee`, e o lojista recebe o `netAmount`.

## Regras de credenciamento do Connect

Antes de cadastrar o primeiro lojista, conheça as regras que a Finvia aplica a toda conta master com Connect. As principais:

| Regra | O que significa |
| - | - |
| Split obrigatório para PSP | Toda transação de PSP divide o valor entre a subconta e a conta master. A conta master não pode ficar com 100% da venda |
| Pré-validação pela plataforma | A conta master confere os dados e documentos do lojista antes de enviar o cadastro |
| 3DS para perfil de alto risco | Lojistas classificados como de alto risco precisam usar 3D Secure no cartão |
| Estorno só pela API | O estorno é pedido por `POST /v1/refunds` |
| Análise em até 24 horas | Tempo médio de análise do cadastro. É mais rápido quando não há divergência documental |
| MCCs vedados | Alguns ramos de atividade não podem ser credenciados como subconta |

O texto completo, com a lista de MCCs vedados, está em [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md).

## Passo a passo

**1. Peça a liberação do Connect**

O módulo é habilitado pela Finvia na conta da plataforma. Sem ele, as rotas do Connect respondem `403` `Fast Connect not enabled.`.

Na criação, cada subconta recebe uma **cópia** das taxas e configurações da conta master vigentes naquele momento. Depois disso, as taxas da subconta são independentes: alterar as taxas da conta master não muda as das subcontas já criadas. Por isso, alinhe com o time Finvia as taxas da conta master antes de cadastrar o primeiro lojista.

**2. Crie a subconta do lojista**

A Feira Online cadastra o Ateliê Barro Fino, uma ceramista de São Paulo (SP), com a chave secreta da conta master. Todos os campos abaixo são obrigatórios, exceto `legalRepresentative.idType`, `address.addressLine2`, `softDescriptor` (texto da fatura do cartão, até 40 caracteres) e `postbackUrl`. Sócios adicionais, quando houver, vão no array opcional `additionalRepresentatives`. Com `canAccessDashboard: true`, o objeto `user` passa a ser obrigatório.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Atelie Barro Fino Ceramica Ltda",
    "tradeName": "Ateliê Barro Fino",
    "companyTaxId": "11222333000181",
    "website": "https://feiraonline.exemplo.com.br/barro-fino",
    "averageMonthlyRevenue": 8000,
    "averageOrderValue": 120,
    "productType": "physical",
    "legalRepresentative": {
      "fullName": "Ana Lima",
      "idNumber": "52998224725",
      "idType": "cpf",
      "dateOfBirth": "1986-04-12",
      "nationality": "Brasileira",
      "email": "ana@email.com",
      "motherName": "Maria Lima",
      "gender": "F",
      "phones": [{ "type": "mobile", "number": "+5511987654321" }]
    },
    "contactEmail": "contato@barrofino.exemplo.com.br",
    "productDescription": "Peças de cerâmica artesanal: vasos, pratos e canecas",
    "softDescriptor": "BARROFINO",
    "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" }],
    "postbackUrl": "https://feiraonline.exemplo.com.br/webhooks/finvia/conta",
    "canAccessDashboard": true,
    "user": {
      "fullName": "Ana Lima",
      "email": "ana@email.com",
      "phone": "+5511987654321"
    },
    "bankAccount": {
      "bankCode": "001",
      "agencyCode": "1234",
      "accountNumber": "567890",
      "accountDigit": "0",
      "accountType": "checking",
      "bankName": "Banco do Brasil",
      "recipientName": "Atelie Barro Fino Ceramica Ltda",
      "recipientDocument": "11222333000181"
    }
  }'
```

```json theme={null}
{
  "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
  "legalRepresentatives": [
    { "id": "2vorkEaaaBbbCccDddEeeFffGgg", "fullName": "Ana Lima", "isPrimary": true }
  ]
}
```

A resposta `201` traz só o `id` da subconta e os representantes, com o representante legal primeiro. Para ver o cadastro completo, use `GET /v1/submerchants/{merchantId}`. A subconta nasce em análise.

| Campo | Regra |
| - | - |
| `address.country` | Três letras (ISO 3166-1 alfa-3), como `BRA`. `BR` é recusado com `400` |
| `companyTaxId` | Com país `BRA`, CPF ou CNPJ com dígito verificador válido. O CNPJ `11222333000181` desta página é fictício e tem dígitos válidos |
| `address.state`, `address.postalCode`, `address.neighborhood` | Com país `BRA`: UF válida, CEP de 8 dígitos e bairro obrigatório |
| `address.addressLine1` | Logradouro e número, separados por vírgula (`Av. Paulista, 1000`). O número é extraído desse formato no credenciamento; sem ele, pode seguir como "S/N" |
| `address.addressLine2` | Complemento opcional, como `Sala 12` |
| `legalRepresentative.idNumber` | CPF válido quando `issuingCountry` é `BRA` ou não é enviado. O CPF `52998224725` desta página é fictício e tem dígitos válidos |
| `user.phone` | Formato internacional E.164, como `+5511987654321` |

| Erro | Causa |
| - | - |
| `400` com `message` em lista | Campo inválido ou faltando, por exemplo `address.country must be a valid ISO31661 Alpha3 code` |
| `400` `Email already registered` | O e-mail de `user` já tem acesso ao painel |
| `409` `Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.` | O CNPJ já existe entre as subcontas da Feira (ou é o da própria conta master) |

O `postbackUrl` do cadastro é a URL que recebe os avisos de mudança de status da subconta. Ele fica salvo nas configurações da subconta. Se você não enviar, a subconta usa a URL da conta master, se houver uma. Para trocar a URL depois, fale com o suporte.

**3. Envie os documentos do KYC**

A rota de documentos recebe `multipart/form-data`, com o nome de cada campo igual ao tipo de documento. Formatos aceitos: PDF, JPG, PNG, GIF, BMP ou WebP, até 50 MB por arquivo.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/document" \
  -u "$FINVIA_API_KEY:" \
  -F "cnpj_card=@cartao-cnpj.pdf" \
  -F "social_contract=@contrato-social.pdf" \
  -F "responsible_document_front=@rg-frente.jpg" \
  -F "responsible_document_back=@rg-verso.jpg" \
  -F "selfie_with_document=@selfie.jpg"
```

Os documentos de pessoa enviados por essa rota ficam ligados ao **representante legal**. Tipo de arquivo inválido, arquivo acima de 50 MB ou nome de campo fora da lista geram `400`. Depois que a subconta é aprovada, novos envios são recusados com `422`.

> [!TIP]
>
> **Para o desenvolvedor:** se a empresa tem mais de um sócio, envie `additionalRepresentatives` na criação e use o fluxo com token para os documentos de cada sócio. Chame `POST /v1/submerchants/{merchantId}/document/upload-token` com o `legalRepresentativeId` do sócio e, em seguida, `POST /v1/document-uploads` com `Authorization: Bearer` e o token recebido. O token vale 300 segundos e é de uso único. Ele também permite que o próprio lojista envie os arquivos pelo navegador, sem expor a chave da plataforma. Detalhes em [Sócios e documentos](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md).

**4. Acompanhe o credenciamento**

O caminho comum é `pending` → `pre_approved` → `active`. A subconta só transaciona quando está `active`.

| Status | Gera aviso? | Significado |
| - | - | - |
| `pending` | Não | Cadastro recebido, em análise. Também é o status depois do reenvio de uma correção |
| `correcting` | Sim | A Finvia pediu correção de dados ou documentos; o motivo vem em `rejectionReason` |
| `pre_approved` | Sim | Documentos conferidos; a subconta está sendo credenciada nas adquirentes e aguarda a aprovação final |
| `active` | Sim | Aprovada e apta a transacionar. Também é enviado no desbloqueio |
| `rejected` | Sim | Reprovada; o motivo vem em `rejectionReason` |
| `blocked` | Sim | Bloqueada |
| `inactive` | Não | Inativada |

O aviso vai para o `postbackUrl` do cadastro, sem envelope e em camelCase. Ele não vai aos endpoints de webhook nem ao `postbackUrl` das cobranças.

```json theme={null}
{
  "merchantId": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
  "status": "correcting",
  "date": "2026-01-13T12:39:48Z",
  "rejectionReason": "Documento de identidade ilegível. Reenvie o RG ou CNH com qualidade adequada."
}
```

Responda com status 2xx em até 10 segundos; qualquer outra resposta conta como falha. O campo `date` é a data de referência do status (no `active`, a data de aprovação, que se mantém num desbloqueio), e não o momento exato do aviso. Trate o aviso como atualização de estado: grave o status e confirme com `GET /v1/submerchants/{merchantId}`. A correção de uma subconta em `correcting` é feita no painel, na gestão de subcontas.

**5. Obtenha as chaves da subconta**

Com a subconta `active`, a Feira busca as chaves dela e guarda no cofre de segredos, associadas ao lojista.

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/api-keys" \
  -u "$FINVIA_API_KEY:"
```

```json theme={null}
{
  "publicKey": "pk_2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
  "secretKey": "sk_2vorkLm4Qp8TzR1sXc7Yb3NdWkE"
}
```

Enquanto a subconta não está ativa, a rota responde `404` "API keys not found for this submerchant.". Em modo de teste, as chaves têm prefixo `sk_test_` e `pk_test_`. A chave secreta e a pública formam um par: se uma for trocada, a outra também muda.

**6. Calcule o percentual do split**

Por padrão, a Finvia aplica o split sobre o [valor líquido](https://docs.fastpaybrasil.com/glossario.md): o valor da venda menos a taxa transacional (fixa mais percentual). A Feira quer 2% do [valor bruto](https://docs.fastpaybrasil.com/glossario.md). Se informar `"percentage": 2`, recebe menos do que deveria. O percentual precisa ser ajustado.

Exemplo com taxas ilustrativas: venda de R\$ 100,00 no cartão em 2x, com taxa transacional de 5% e taxa fixa de R\$ 0,40.

| Passo | Conta | Resultado |
| - | - | - |
| Valor líquido (L) | 100 × (1 − 0,05) − 0,40 | R\$ 94,60 |
| Comissão desejada | 2% × R\$ 100,00 | R\$ 2,00 |
| Split a informar (s) | 2,00 ÷ 94,60, arredondado para cima na quarta casa | **2,1142%** |
| Conferência | 2,1142% × 94,60 | R\$ 2,00 para a Feira e R\$ 92,60 para o lojista |

A fórmula geral é `L = V × (1 − f) − c` e `s = (p × V) ÷ L`. Nela, `V` é o valor bruto, `f` o percentual da taxa transacional, `c` a taxa fixa e `p` a comissão sobre o bruto. Arredondar `s` para cima na quarta casa evita que a comissão fique um centavo abaixo do alvo.

As taxas vêm da própria subconta. Consulte com a chave da conta master:

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/fees-info" \
  -u "$FINVIA_API_KEY:"
```

A resposta traz `fees` como uma lista plana. Cada linha tem `feeType` (`tx_spread` ou `anticipation`), `paymentMethod`, `currencyCode`, `brand` e `definition` (`fixed` e `percentages`). Para chegar à taxa transacional de uma venda em `n` parcelas, filtre as linhas `tx_spread` pelo método e pela moeda, use a linha da bandeira do cartão (ou a linha `brand: null`, se não houver uma da bandeira) e leia `percentages[n-1]` como `f` e `fixed` como `c`.

> [!WARNING]
>
> **Antecipação muda a base.** A taxa de antecipação (`anticipation`) só entra na conta quando o lojista antecipa o recebível. Nesse caso, o split é recalculado sobre o valor já descontada a taxa de antecipação, e a Feira recebe proporcionalmente menos. A taxa de antecipação é mensal (só `percentages[0]` é usado), multiplicada pelo número de meses até o vencimento de cada parcela, com mínimo de 1 mês.

Se `fees` vier vazio, ou sem linha para o método e a moeda da venda, a subconta está sem taxas configuradas e as cobranças dessa combinação são recusadas com `422` `Fees not configured`. Nesse caso, acione o suporte da Finvia. O detalhe, com o código de cálculo, está em [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md).

**7. Crie a venda na subconta, com split para a plataforma**

A cobrança é autenticada com a **chave secreta da subconta do lojista**. É isso que vincula a venda ao lojista. O `merchantId` do split é o ID da conta master da Feira.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$CHAVE_SUBCONTA_BARRO_FINO:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "BRL",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "document": { "type": "cpf", "id": "52998224725" }
    },
    "paymentMethod": {
      "type": "credit_card",
      "number": "1111222233334444",
      "holderName": "MARIA SOUZA",
      "expirationMonth": "10",
      "expirationYear": "2028",
      "cvv": "123",
      "installments": 2
    },
    "items": [
      { "title": "Vaso de cerâmica", "type": "physical", "description": "Peça artesanal, 30 cm", "unit_price": 100, "quantity": 1 }
    ],
    "shippingAddress": {
      "postalCode": "01310100",
      "addressLine1": "Av. Paulista, 1000",
      "addressLine2": "Apto 51",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    },
    "split": [
      { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 2.1142 }
    ],
    "metadata": { "pedidoFeira": "FO-88120", "lojista": "barro-fino" },
    "postbackUrl": "https://feiraonline.exemplo.com.br/webhooks/finvia/postback"
  }'
```

Os 97,8858% restantes do líquido ficam com o lojista, que originou a venda. No exemplo, `36OO3bcGjhPjjF3tzrqOGcmQuKo` é a conta master da Feira e `2vorkLm4Qp8TzR1sXc7Yb3NdWkE` é a subconta do Ateliê. O `split` enviado na requisição vale só para essa venda e prevalece sobre a regra padrão da conta. Sem `split` na requisição, a API aplica a regra padrão da subconta para aquele método e moeda ou, se ela não tiver uma, a regra padrão definida pela conta master.

Como a venda pertence à subconta, os eventos dela vão para os endpoints cadastrados na subconta, para os endpoints da conta master marcados para receber eventos das subcontas e para o `postbackUrl` da cobrança. O payload traz o `merchant_id` da subconta, e assim a Feira identifica o lojista.

**8. Confira o split da venda**

O campo `splits` aparece só na consulta individual da cobrança. Ele não vem na resposta de criação nem na listagem.

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI" \
  -u "$CHAVE_SUBCONTA_BARRO_FINO:"
```

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "paid",
  "amount": 100,
  "splits": [
    {
      "id": "2vorkSp1tQx7RmB4nZc9WdLk3Hv",
      "destinyMerchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
      "destinyMerchantName": "Feira Online",
      "splitPercentage": "2.11420000",
      "splitAmount": 2,
      "referenceAmount": "net"
    }
  ]
}
```

| Campo | O que traz |
| - | - |
| `destinyMerchantId` | Conta que recebe a parte (o `merchantId` enviado em `split`) |
| `destinyMerchantName` | Nome fantasia da conta que recebe |
| `splitPercentage` | Percentual, como texto decimal. Converta para número antes de comparar |
| `splitAmount` | Valor exibido para quem recebe, em reais, truncado em 2 casas |
| `referenceAmount` | Base de cálculo: `net` (valor líquido, o padrão) ou `gross` (valor bruto) |

O `splitAmount` muda de significado ao longo da vida da venda. Enquanto houver parcelas a liquidar e nenhuma antecipação, ele mostra uma simulação: o valor que a Feira teria se o lojista antecipasse, já descontada a taxa de antecipação estimada, e por isso fica abaixo de R\$ 2,00. Depois que as parcelas liquidam sem antecipação, ele mostra o repasse efetivo, o percentual sobre o líquido (R\$ 2,00 no exemplo). Depois de uma antecipação, mostra o valor recalculado sobre o valor antecipado. Na conciliação, confira `splitPercentage` e compare `splitAmount` com o alvo só depois da liquidação. Essa conferência é o cenário SPL-05 da homologação.

**9. Pague o lojista: o saque**

O saque da subconta é pedido com a chave secreta da conta master. Ele sai por **Pix para a chave CNPJ da subconta**: a chave Pix do tipo CNPJ igual ao CNPJ do cadastro. Não é possível escolher outra chave. A moeda é sempre `BRL` e o valor vai em reais, com mínimo de R\$ 1,00.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/payout-requests" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 850.5 }'
```

```json theme={null}
{ "id": "2vorkEbbbCccDddEeeFffGggHhh" }
```

O `id` devolvido é o do pedido de saque, diferente do `id` da subconta. O valor bruto sai do saldo disponível da subconta na criação. O saque nasce `pending` e sempre passa por aprovação da Finvia. A taxa de saque (`payoutFee`) é calculada na criação e soma uma parte fixa e uma percentual: `payoutFee = taxa fixa + (amount × taxa percentual ÷ 100)`. O lojista recebe `netAmount = amount − payoutFee`.

> [!WARNING]
>
> Antes do primeiro saque, o lojista precisa cadastrar o CNPJ como chave Pix em uma conta bancária da empresa. A API não confere se a chave existe: sem ela, o Pix não é concluído e o caso precisa ser tratado com o suporte.

| Resposta | Causa |
| - | - |
| `400` com `message` em lista | Valor inválido, por exemplo `amount must not be less than 1` |
| `403` `Fast Connect not enabled.` | Connect não habilitado na conta da credencial |
| `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chave de teste: não existe saque no Modo Teste |
| `404` `SubMerchant not found` | Subconta inexistente ou de outra conta master |
| `422` `SubMerchant account is not active` | Subconta fora de `active` |
| `422` `SubMerchant is blocked. Withdrawals are not allowed.` | Subconta bloqueada |
| `422` `SubMerchant CNPJ not configured` | CNPJ não cadastrado na subconta |
| `422` `Insufficient balance. Required: X, Available: Y` | Saldo disponível menor que o valor |
| `422` `You already have a pending withdrawal request for this currency` | Já existe um saque `pending` |
| `422` `Maximum withdrawal amount is X BRL` | Acima do limite por saque configurado para a conta |
| `422` `Withdrawals are disabled for this submerchant` | Saques desabilitados na subconta |
| `422` `Payout fees not configured` | Taxa de saque não configurada |

**10. Acompanhe o saque**

O saque tem três status: `pending` (criado, valor reservado, aguardando decisão), `approved` (aprovado e enviado para pagamento) e `rejected` (recusado; o valor volta ao saldo disponível e o motivo fica em `rejectionReason`).

Quando o saque de uma subconta é aprovado ou recusado, a Finvia envia `payout.approved` ou `payout.rejected` aos endpoints cadastrados na subconta e aos endpoints da conta master marcados para receber eventos das subcontas. A forma mais simples é um único endpoint na conta master, cadastrado com `include_submerchants: true` em `POST /v1/webhook-endpoints` ou com a opção de incluir subcontas em **Configurações** > **Webhooks** no painel.

```json theme={null}
{
  "id": "2vorkEbbbCccDddEeeFffGggHhh",
  "event": "payout.approved",
  "data": {
    "id": "2vorkEbbbCccDddEeeFffGggHhh",
    "merchantId": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
    "amount": "850.50000000",
    "currency": "BRL",
    "status": "approved",
    "payoutFee": "1.00000000",
    "netAmount": "849.50000000"
  }
}
```

O `id` da raiz é o id do saque e se repete nos eventos do mesmo saque: deduplique por `id` + `event`. `amount`, `payoutFee` e `netAmount` chegam como texto decimal com 8 casas; converta antes de somar ou exibir. O webhook de saque não tem assinatura, então confirme o status pela listagem antes de agir:

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=2vorkLm4Qp8TzR1sXc7Yb3NdWkE&status=pending&page=1&size=20" \
  -u "$FINVIA_API_KEY:"
```

A resposta é `{ data, total, page, size, pages, pendingCount }`, do mais recente para o mais antigo. `pendingCount` é o total de saques pendentes com os mesmos filtros, sem considerar o de status. Cada item traz `id`, `merchantId`, `amount`, `currency`, `status`, `payoutFee`, `externalAccountDetails` (com `type` e `pix_key`), `processedAt`, `createdAt`, `merchantLegalName` e `merchantEmail`, com os valores em texto decimal. Com a chave da conta master, a listagem traz os saques de todas as subcontas: filtre por `merchantId` para ver um lojista. Também é possível filtrar por `currency` e por data de criação, com `createdAtStart` e `createdAtEnd` (`AAAA-MM-DD`).

## Quanto a Feira recebe no mês

Com os números do cenário (6.500 pedidos, ticket médio de R\$ 100,00), o volume bruto é R\$ 650.000,00 e a comissão alvo é 2% disso: R\$ 13.000,00. Para simplificar, suponha 2.600 pedidos em Pix e 3.900 no cartão em 2x, com as taxas ilustrativas desta página (Pix com 1,5% e sem taxa fixa; cartão 2x com 5% e R\$ 0,40) e sem antecipação.

| Pedidos | Líquido por pedido | Split informado | Feira recebe por pedido | Feira recebe no mês |
| - | - | - | - | - |
| 2.600 em Pix | R\$ 98,50 | 2,0305% | R\$ 2,00 | R\$ 5.200,00 |
| 3.900 no cartão 2x | R\$ 94,60 | 2,1142% | R\$ 2,00 | R\$ 7.800,00 |
| **Total** | | | | **R\$ 13.000,00** |

Se a Feira enviasse `"percentage": 2` em todas as vendas, receberia R\$ 1,97 por pedido em Pix e R\$ 1,89 por pedido no cartão 2x: R\$ 12.493,00 no mês, R\$ 507,00 abaixo do combinado. Vendas em 3x a 6x têm outras taxas e pedem outro percentual, calculado da mesma forma.

## Liquidação e repasse do split

| Tema | Como funciona |
| - | - |
| Cálculo | O valor de cada participante é calculado na criação da cobrança e dividido igualmente entre as parcelas |
| Prazo no cartão | Cada parcela é repassada 30 dias corridos depois da criação da cobrança: 1ª parcela em D+30, 2ª em D+60 e assim por diante. No exemplo em 2x, a Feira recebe R\$ 1,00 em D+30 e R\$ 1,00 em D+60 |
| Prazo no Pix | No mesmo dia, logo após a confirmação do pagamento |
| Destino | O valor sai do saldo disponível do lojista e entra no saldo disponível da Feira. Antes da liquidação, o valor inteiro fica no saldo a liberar do lojista e a Feira não vê nada no saldo |
| Retenção | Se a Finvia reter o recebível do lojista, a liquidação e o repasse ficam suspensos até a liberação. A parte ligada à reserva financeira do lojista é repassada quando a reserva é liberada |
| Antecipação | Só o lojista, dono do recebível, antecipa. Na antecipação, o repasse acontece na hora, calculado sobre o valor já descontada a taxa de antecipação |
| Estorno | Se a venda for estornada depois do repasse, a parte já repassada é debitada do saldo da Feira e devolvida ao lojista |
| Cobrança recusada | O split pode aparecer na consulta, mas o repasse só acontece quando a cobrança é paga |
| Assinaturas | As cobranças recorrentes de assinatura não recebem split |

Duas opções existem sob consulta, configuradas pela Finvia: usar o valor bruto como base do split (aí o percentual incide sobre o bruto e não muda na antecipação) e a conta master absorver a taxa de antecipação das subcontas. Fale com o time comercial se o seu modelo precisar de uma delas.

## Regras e cuidados

> [!WARNING]
>
> **O percentual do split incide sobre o líquido.** Repassar o mesmo percentual que a plataforma cobra sobre o bruto faz a plataforma receber menos. Calcule o percentual a cada venda com as taxas reais da subconta.

> [!WARNING]
>
> **Saque em reais.** `"amount": 100` são R\$ 100,00. Enviar `10000` achando que é R\$ 100,00 gera um saque de R\$ 10.000,00.

* **Soma dos percentuais.** Não pode passar de 100%. O que sobrar fica com o originador, a conta que criou a cobrança.
* **Mesmo grupo.** Todas as contas do split precisam pertencer ao mesmo [grupo Connect](https://docs.fastpaybrasil.com/glossario.md) (a conta master e as subcontas dela). Relações permitidas: conta master para subconta, subconta para conta master e subconta para subconta do mesmo grupo.
* **Chave certa.** A venda criada com a chave da conta master fica na conta master. Para vincular a venda ao lojista, use a chave da subconta.
* **Regra padrão de split.** No painel, na gestão de subcontas, a plataforma pode definir participantes e percentuais padrão por meio de pagamento. O `split` enviado na cobrança prevalece sobre o padrão naquela venda.
* **Taxas copiadas na criação.** Mudar as taxas da conta master não muda as das subcontas já criadas. A Finvia pode replicar uma alteração para as subcontas por operação interna.
* **Estorno.** É sempre da venda inteira e pedido pela conta dona da cobrança, com a chave da subconta. Quem só recebe split não consegue estornar a venda.
* **Documentos depois da aprovação.** Ficam bloqueados (`422`). Revise os arquivos antes de enviar.
* **URLs de documentos.** A listagem de sócios com `include=documents` devolve URLs assinadas que expiram em 1 hora. Não guarde essas URLs.

## Variações do caso

> [accordion] Variação PSP: parceiro que cadastra seus lojistas como subcontas
>
> A **PagaFácil Serviços Digitais** é um PSP parceiro que atende 900 pequenos negócios (academias, pet shops, oficinas) e cadastra cada um deles como subconta, ganhando uma margem por transação. O desenho é o mesmo do marketplace:
>
> | Marketplace | PSP |
> | - | - |
> | Feira Online é a conta master | PagaFácil é a conta master |
> | Cada lojista é uma subconta | Cada cliente da PagaFácil é uma subconta |
> | Venda criada no site da Feira, com a chave do lojista | Cobrança criada pelo sistema da PagaFácil, com a chave do cliente |
> | Comissão da plataforma via `split` para a conta master | Margem da PagaFácil via `split` para a conta master |
> | Lojista saca para a chave CNPJ dele | Cliente saca para a chave CNPJ dele |
>
> As [regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md) pesam mais no PSP, porque ele cadastra negócios de ramos variados:
>
> * toda cobrança divide o valor entre a subconta e a PagaFácil, e a PagaFácil não pode ficar com 100% da venda;
> * a PagaFácil confere os dados e os documentos de cada cliente antes de enviar o cadastro;
> * clientes com perfil de alto risco precisam usar 3D Secure no cartão;
> * o estorno é pedido só pela API (`POST /v1/refunds`);
> * a análise do cadastro de cada cliente leva, em média, até 24 horas;
> * clientes de MCCs vedados não podem ser credenciados.
>
> Outras diferenças práticas: o `productType` (`digital`, `physical` ou `both`) precisa refletir o que cada cliente vende. A PagaFácil recebe os eventos de cobrança dos clientes em um endpoint da conta master com `include_submerchants: true` e repassa a cada um. O modelo de repasse está em [Agências e white label](https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md).

> [accordion] E se o pedido tiver produtos de dois lojistas?
>
> Cada cobrança tem um único originador. Uma saída é criar uma cobrança por lojista no mesmo checkout, cada uma com a chave da subconta dele e o split da plataforma. Outra é criar a cobrança na subconta de um lojista e mandar a parte do outro por split de subconta para subconta, que é uma relação permitida dentro do mesmo grupo. Na segunda opção, o cálculo precisa considerar a comissão da plataforma e a parte do segundo lojista sobre o mesmo líquido. O lojista que só recebe split não recebe os eventos dessa cobrança: eles vão só para o dono da cobrança.

> [accordion] E se o cliente pagar com Pix?
>
> O `split` funciona igual no Pix. A diferença está nas taxas e no prazo: use as linhas de `fees` com `paymentMethod` `pix` para chegar ao `f` e ao `c`, e conte com o repasse no mesmo dia, logo após a confirmação. Teste os dois métodos na homologação (cenário SPL-06).

> [accordion] E se a plataforma cobrar uma taxa fixa por venda, além do percentual?
>
> O split aceita só percentual. Converta a taxa fixa em percentual daquela venda: some a parte fixa à comissão desejada em reais antes de dividir pelo líquido. Exemplo: comissão de 2% mais R\$ 1,00 em uma venda de R\$ 100,00 no cartão 2x dá R\$ 3,00, e `s = 3,00 ÷ 94,60 = 3,1713%`.

## Checklist de implementação

* [ ] Connect habilitado pela Finvia na conta da plataforma, com as taxas da conta master definidas antes do primeiro cadastro
* [ ] Regras de credenciamento conhecidas, inclusive a lista de MCCs vedados
* [ ] Criação de subconta com país `BRA`, CNPJ e CPF válidos, CEP de 8 dígitos e `addressLine1` com o número depois da vírgula
* [ ] Tratamento dos erros `400` e `409` na criação da subconta
* [ ] Envio dos documentos de empresa e do representante; fluxo com token para sócios adicionais
* [ ] Tratamento dos avisos de status, separando status que geram aviso dos que não geram, e resposta 2xx
* [ ] Orientação ao lojista para corrigir dados pelo painel quando vier `correcting`
* [ ] Chaves da subconta obtidas só depois de `active` e guardadas em cofre de segredos
* [ ] Cálculo do percentual de split com as taxas de `fees-info`, por bandeira e parcela
* [ ] Vendas criadas com a chave da subconta e `split` para a conta master
* [ ] Soma dos percentuais até 100%
* [ ] Conciliação do campo `splits` levando em conta a simulação de antecipação antes da liquidação
* [ ] Lojistas orientados a cadastrar o CNPJ como chave Pix antes do primeiro saque
* [ ] Saques em reais, com tratamento dos erros `400`, `403`, `404` e `422`
* [ ] Endpoint da conta master com `include_submerchants: true` (ou endpoints nas subcontas) para os avisos de saque
* [ ] Valores de saque convertidos de texto decimal e saques conferidos pela listagem

## Como homologar

| Funcionalidade | Cenários |
| - | - |
| Subcontas | FC-01 (criar), FC-02 (documentos), FC-03 (consultar até `active`), FC-04 (chaves), FC-05 (cobrança na subconta), FC-06 (split entre subcontas), FC-07 (saque em reais), FC-08 (aviso de status) |
| Split | SPL-01 (1 recebedor), SPL-02 (2 ou mais), SPL-03 (percentual inválido), SPL-04 (recebedor fora do grupo), SPL-05 (conferência do valor), SPL-06 (Pix e cartão parcelado) |

SPL-01, SPL-02 e SPL-05 conferem `destinyMerchantId`, `splitPercentage` e `splitAmount` em `GET /v1/charges/{id}`. No SPL-05, compare o valor com o líquido × percentual, lembrando que antes da liquidação o `splitAmount` é uma simulação menor. O FC-07 não roda com a chave de teste, que recebe `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`: combine com o suporte da Finvia como evidenciar o saque. Detalhes no [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

## Veja também

> [card] [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md)
>
> Conta master, subcontas e permissões.

> [card] [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md)
>
> O que a Finvia exige de toda conta master e das subcontas.

> [card] [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
>
> Fórmula e código para comissão sobre o bruto.

> [card] [Saques](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md)
>
> Saque da subconta, taxas e acompanhamento.


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