Skip to main content
Cada vendedor, lojista ou cliente que opera dentro da sua estrutura Connect precisa de uma subconta (SubMerchant). O ciclo tem três partes: você cadastra a empresa, envia os documentos para a análise de KYC (a verificação da identidade das pessoas e dos dados da empresa) e, quando a Finvia aprova, a subconta recebe as próprias chaves de API para vender.
Para o negócio: a subconta só vende depois de aprovada. Monte o formulário de cadastro da sua plataforma já com todos os campos e documentos listados nesta página. Dados faltando ou documentos ilegíveis levam a pedidos de correção (status correcting), e o cadastro volta para a fila de análise.

Quando usar

  • Entrada de um novo vendedor no marketplace: o vendedor preenche o cadastro na sua plataforma e a sua aplicação cria a subconta pela API.
  • Credenciamento de lojistas por um PSP: cada lojista credenciado vira uma subconta com dados bancários e documentos próprios.
  • Migração de uma base de clientes para o Connect: a criação em lote é feita chamando a rota uma vez por empresa.
Se a empresa tem mais de um sócio e você precisa enviar documentos de cada um, veja também Sócios e documentos. Os documentos exigidos, o prazo médio da análise, os motivos de recusa e os ramos (MCCs) não aceitos estão em Regras de credenciamento.

Como funciona

A sequência abaixo mostra o credenciamento de uma subconta, do cadastro até as chaves de API.
1

Pré-valide o lojista

Confira do seu lado os dados e documentos do lojista antes de enviar, como pedem as Regras de credenciamento.
2

Crie a subconta

POST /v1/submerchants com a chave secreta da conta master. A resposta traz o id da subconta e a lista legalRepresentatives. A subconta começa com status pending.
3

Envie os documentos

POST /v1/submerchants/{id}/document em multipart/form-data, um arquivo por tipo de documento.
4

Acompanhe a análise

A Finvia analisa o cadastro. Você acompanha pelo aviso de mudança de status e pela consulta GET /v1/submerchants/{id}.
5

Corrija, se pedido

Se o status for para correcting, o motivo vem no aviso. Depois que a correção é reenviada, o cadastro volta para a análise.
6

Obtenha as chaves

Com o status active, busque as chaves em GET /v1/submerchants/{id}/api-keys e guarde no seu cofre de segredos.

Regras de negócio

Com país BRA, o companyTaxId, o idNumber do representante legal e dos sócios (CPF) e o bankAccount.recipientDocument são validados com dígitos verificadores. Os números desta página são válidos só para teste de formato. Use os documentos reais da empresa e das pessoas.

Dados exigidos na criação

O corpo de POST /v1/submerchants é organizado em blocos. Todos os campos marcados como obrigatórios precisam estar presentes.

Empresa

Para o negócio: website, averageMonthlyRevenue e averageOrderValue são a URL do lojista, a expectativa de faturamento e o ticket médio que as Regras de credenciamento exigem. productType precisa refletir o que o vendedor realmente vende; se ele vende os dois tipos, cadastre both.

Endereço

Objeto legalRepresentative, obrigatório.

Sócios adicionais

Array additionalRepresentatives, opcional. Cada item tem o mesmo formato do representante legal. O idNumber do sócio é o CPF, validado com dígitos verificadores. O envio dos documentos de cada sócio está em Sócios e documentos.

Conta bancária

Objeto bankAccount, obrigatório.

Acesso ao painel

Status do credenciamento

A subconta passa por estes status ao longo da vida: O caminho comum é pending, depois pre_approved, depois active. A aprovação final só parte de pre_approved. O pedido de correção (correcting) só acontece a partir de pending ou pre_approved; depois que a correção é reenviada, a subconta volta para a análise. Uma conta active pode ser bloqueada (blocked) e desbloqueada, ou inativada (inactive). O desenho abaixo mostra todas as mudanças de status possíveis. As setas pontilhadas são as mudanças que não geram aviso.

Status que geram aviso

Nem toda mudança gera notificação. Só estas cinco transições disparam o aviso de mudança de status: pending (inclusive a volta para análise depois de uma correção) e a inativação (inactive) não geram aviso. Para esses casos, consulte a subconta. O aviso vai para o postbackUrl informado na criação da subconta. A URL fica salva nas configurações da subconta; para alterá-la depois, fale com o suporte. Sem postbackUrl, a subconta usa a URL de aviso de status da conta master, se a master tiver uma. O aviso não vai aos endpoints de webhook do painel nem ao postbackUrl das cobranças. O aviso é um POST sem envelope, com campos em camelCase:
O campo date é a data de referência do status e pode ser diferente do momento exato da mudança. Em active, por exemplo, é a data da aprovação, mesmo num desbloqueio.
Para o desenvolvedor: responda o aviso com um status 2xx em até 10 segundos; qualquer outro resultado conta como falha de entrega. Use merchantId + status + date como chave para ignorar avisos repetidos e confirme o status atual com GET /v1/submerchants/{id}. Detalhes em Webhooks de conta.

Passo a passo

1. Crie a subconta

Resposta 201:
Guarde o id: ele é usado em todas as chamadas seguintes da subconta, e é o merchantId dela no split e no saque.

2. Envie os documentos

A rota POST /v1/submerchants/{id}/document recebe os arquivos em multipart/form-data. O nome de cada campo é o tipo do documento: Para uma empresa brasileira, o credenciamento pede contrato social, cartão CNPJ, documento do responsável frente e verso e selfie com documento; para MEI, cartão CNPJ e certificado de MEI. Não há campo próprio para o certificado de MEI: fale com o suporte para enviá-lo. A lista completa está em Regras de credenciamento. É preciso enviar pelo menos um arquivo por chamada, e você pode enviar todos de uma vez.
cURL
Para o desenvolvedor: não defina o cabeçalho Content-Type manualmente em envios multipart. O cURL (com -F) e as bibliotecas HTTP montam o cabeçalho com o separador (boundary) correto. A resposta de sucesso é 201, sem corpo.
Esta rota vincula os documentos de pessoa sempre ao representante legal. Se a empresa tem só um representante, ela é tudo o que você precisa. Para documentos de sócios adicionais, ou para receber os arquivos direto do navegador do vendedor sem expor a sua chave, use o fluxo com token descrito em Sócios e documentos.

3. Consulte até active

cURL
O campo status da resposta mostra a situação atual. Quando a subconta é aprovada, approvedAt passa a ter a data da aprovação. Use o aviso de mudança de status como gatilho principal e a consulta para confirmar ou para casos sem aviso (como pending e inactive). Para acompanhar várias subcontas, GET /v1/submerchants aceita o filtro status com os sete valores. Para mais de um status, repita o parâmetro: ?status=pending&status=correcting. Veja os demais filtros em Listar subcontas.

4. Obtenha as chaves da subconta

cURL
200
Se a subconta não tiver chaves, a resposta é:
404
Em modo de teste, as chaves vêm com prefixo sk_test_ e pk_test_.
A secretKey é a chave secreta da subconta: com ela, a sua plataforma cria cobranças em nome da subconta. Guarde em cofre de segredos, no servidor, associada ao id da subconta. Nunca envie a chave secreta para o vendedor por e-mail ou mensagem, nem para o navegador.

5. Corrija um cadastro em correcting

Quando a Finvia pede correções, o aviso chega com status correcting e o motivo em rejectionReason. A correção dos dados é feita pelo painel da Finvia, na gestão de subcontas (a API não oferece essa operação). Depois do reenvio, a subconta volta para a análise. O status rejected indica que o cadastro foi reprovado.
Para o negócio: combine com o time de operação quem acompanha as correções pendentes no painel. Uma boa prática é mostrar o rejectionReason ao vendedor na sua plataforma, coletar o dado ou documento correto e só então fazer a correção no painel.

Erros comuns

As mensagens de erro misturam português e inglês. Trate o erro pelo código HTTP, sem depender do texto da mensagem.

Perguntas frequentes

Sim. Cada chamada precisa ter pelo menos um arquivo. Você pode mandar os documentos da empresa em uma chamada e os do representante em outra.
Não pela API. Depois da aprovação, novos envios são bloqueados e a rota responde 422.
Não. Se você não enviar legalRepresentative.address, o representante usa o endereço da empresa.
O aviso de mudança de status traz o campo rejectionReason quando o status é rejected ou correcting. Para ver o status de cada documento de pessoa, use a listagem de representantes com include=documents (Sócios e documentos).
Não é obrigatório. Defina canAccessDashboard como false se a sua plataforma vai oferecer toda a experiência ao vendedor. Com true, informe o user que vai acessar o painel.
É o nome que aparece na fatura do cartão do cliente, com até 40 caracteres.
O tempo médio de credenciamento é de até 24 horas, e é mais rápido quando não há divergência nos documentos. Veja Regras de credenciamento.

Como testar

Cenários do roteiro de homologação:

Veja também

Sócios e documentos

Sócios adicionais e envio de documentos com token.

Webhooks de conta

Formato completo do aviso de mudança de status.

Criar subconta

Referência completa da rota.

Regras de credenciamento

Documentos exigidos, motivos de recusa e MCCs não aceitos.