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.
Regras de negócio
Relações de split permitidas
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.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.36OO3bcGjhPjjF3tzrqOGcmQuKo representa o id da conta que recebe a comissão (por exemplo, a master).
Erros comuns
Perguntas frequentes
Como peço a liberação do Connect?
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.
Preciso configurar as taxas de cada subconta?
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. Se
fees vier vazio, fale com o suporte: as cobranças dessa subconta são recusadas até a configuração.A subconta pode vender antes de ser aprovada?
A subconta pode vender antes de ser aprovada?
Não. A subconta só fica apta a transacionar com status
active.A subconta pode acessar o painel da Finvia?
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.Posso dividir uma venda entre duas subcontas sem passar pela master?
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:- 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.
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.

