Skip to main content
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.
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.

Implementar este caso com um assistente de IA

Open in Cursor

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:

O que a Finvia resolve

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: 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

O desenho abaixo mostra a ordem das chamadas, do cadastro do lojista à primeira venda com split. 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. 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: O texto completo, com a lista de MCCs vedados, está em Regras de credenciamento.

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

Acompanhe o credenciamento

O caminho comum é pending → pre_approved → active. A subconta só transaciona quando está active.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.
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.
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: o valor da venda menos a taxa transacional (fixa mais percentual). A Feira quer 2% do valor bruto. 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.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:
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.
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.
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.
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.
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.
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.
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.
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.
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:
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. 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

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

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

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:As regras de credenciamento 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.
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.
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).
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

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.

Veja também

Connect

Conta master, subcontas e permissões.

Regras de credenciamento

O que a Finvia exige de toda conta master e das subcontas.

Cálculo de split

Fórmula e código para comissão sobre o bruto.

Saques

Saque da subconta, taxas e acompanhamento.