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.
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
Dados exigidos na criação
O corpo dePOST /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
Representante legal
ObjetolegalRepresentative, obrigatório.
Sócios adicionais
ArrayadditionalRepresentatives, 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
ObjetobankAccount, 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:
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.
Passo a passo
1. Crie a subconta
201:
id: ele é usado em todas as chamadas seguintes da subconta, e é o merchantId dela no split e no saque.
2. Envie os documentos
A rotaPOST /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
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
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
404
sk_test_ e pk_test_.
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
Posso enviar os documentos em várias chamadas?
Posso enviar os documentos em várias chamadas?
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.
Consigo trocar um documento depois que a subconta foi aprovada?
Consigo trocar um documento depois que a subconta foi aprovada?
Não pela API. Depois da aprovação, novos envios são bloqueados e a rota responde
422.O endereço do representante é obrigatório?
O endereço do representante é obrigatório?
Não. Se você não enviar
legalRepresentative.address, o representante usa o endereço da empresa.Como sei por que a subconta foi recusada?
Como sei por que a subconta foi recusada?
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).A subconta precisa de acesso ao painel?
A subconta precisa de acesso ao painel?
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.Para que serve o softDescriptor?
Para que serve o softDescriptor?
É o nome que aparece na fatura do cartão do cliente, com até 40 caracteres.
Quanto tempo leva a análise?
Quanto tempo leva a análise?
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.

