Implementar este caso com um assistente de IA
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
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
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:Passo a passo
Peça a liberação do Connect
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.Crie a subconta do lojista
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.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.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.Envie os documentos do KYC
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.400. Depois que a subconta é aprovada, novos envios são recusados com 422.Acompanhe o credenciamento
pending → pre_approved → active. A subconta só transaciona quando está active.postbackUrl do cadastro, sem envelope e em camelCase. Ele não vai aos endpoints de webhook nem ao postbackUrl das cobranças.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.Obtenha as chaves da subconta
active, a Feira busca as chaves dela e guarda no cofre de segredos, associadas ao lojista.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.Calcule o percentual do split
"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.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: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.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.Crie a venda na subconta, com split para a plataforma
merchantId do split é o ID da conta master da Feira.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.Confira o split da venda
splits aparece só na consulta individual da cobrança. Ele não vem na resposta de criação nem na listagem.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.Pague o lojista: o saque
BRL e o valor vai em reais, com mínimo de R$ 1,00.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.Acompanhe o saque
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.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:{ 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."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
Regras e cuidados
- 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
splitenviado 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=documentsdevolve URLs assinadas que expiram em 1 hora. Não guarde essas URLs.
Variações do caso
Variação PSP: parceiro que cadastra seus lojistas como subcontas
Variação PSP: parceiro que cadastra seus lojistas como subcontas
- 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.
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.E se o pedido tiver produtos de dois lojistas?
E se o pedido tiver produtos de dois lojistas?
E se o cliente pagar com Pix?
E se o cliente pagar com Pix?
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).E se a plataforma cobrar uma taxa fixa por venda, além do percentual?
E se a plataforma cobrar uma taxa fixa por venda, além do percentual?
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 eaddressLine1com o número depois da vírgula - Tratamento dos erros
400e409na 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
activee 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
splitpara a conta master - Soma dos percentuais até 100%
- Conciliação do campo
splitslevando 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,404e422 - 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
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.

