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

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: 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: 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. 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). A subconta só usa as chaves, vende e saca depois de aprovada (active).
A rota GET /v1/fast-connect/sub-accounts/{id}/fees-info 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.

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 e Regras de credenciamento.
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.
6

Liquidação e saque

Cada parte do split é repassada parcela a parcela, quando o recebível do originador é 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 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 e Saques da subconta.
O desenho abaixo mostra o caminho do dinheiro em uma venda com split, do pagamento ao saque da subconta. 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 e Saques da subconta.

Regras de negócio

Relações de split permitidas

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

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

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.
No passo 4, 36OO3bcGjhPjjF3tzrqOGcmQuKo representa o id da conta que recebe a comissão (por exemplo, a master).

Erros comuns

Perguntas frequentes

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.
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. Se fees vier vazio, fale com o suporte: as cobranças dessa subconta são recusadas até a configuração.
Não. A subconta só fica apta a transacionar com status active.
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.
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:
  • 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

Subcontas e KYC

Cadastro, documentos e status de aprovação.

Split de pagamentos

Regras e exemplos de divisão de vendas.

Saques da subconta

Como a subconta retira o saldo via Pix.

Regras de credenciamento

Regras para PSPs e plataformas, documentos e MCCs não aceitos.

Marketplace e PSP

Caso de uso completo com subcontas e split.