Skip to main content
Toda subconta (SubMerchant) criada no Connect passa por análise antes de poder vender. Este aviso informa ao seu sistema quando o status de aprovação da subconta muda: pré-aprovada, aprovada, devolvida para correção, rejeitada, bloqueada ou desbloqueada.
Para o negócio: num marketplace ou numa plataforma que cadastra vendedores, este aviso permite liberar o vendedor para vender no momento em que a conta é aprovada e avisá-lo assim que a análise pedir uma correção. Sem ele, o seu time precisa conferir o painel para saber em que pé está cada cadastro.

Quando usar

Como funciona

1

Subconta criada com a URL de aviso

A conta master cria a subconta em POST /v1/submerchants e informa postbackUrl. A subconta nasce com status pending, e essa criação não gera aviso.
2

Análise da Finvia

A equipe da Finvia analisa os dados e os documentos enviados.
3

Mudança de status

A cada mudança para pre_approved, correcting, active, rejected ou blocked, a Finvia envia um POST com o novo status para a URL de aviso de status da subconta.
4

Seu sistema reage

Libera a subconta, pede correção ao vendedor ou encerra o cadastro, conforme o status.

Canal e configuração

O aviso de status de conta tem um canal próprio:
Para o desenvolvedor: informe postbackUrl na criação de cada subconta, mesmo que a master já tenha uma URL configurada. Assim o destino fica explícito no seu código e você não depende da cópia das configurações da master.

Status possíveis e status que geram aviso

A subconta tem sete status possíveis no ciclo de vida, mas só cinco geram aviso.
Não espere aviso para pending nem para inactive. Para saber desses status, consulte a subconta em GET /v1/submerchants/{merchantId}. Em especial, depois que o vendedor reenvia os dados corrigidos, a conta volta para análise sem aviso. O próximo aviso chega só quando a análise avançar.

Ciclo de vida da aprovação

O fluxo comum é pending → pre_approved → active. O desenho abaixo mostra todas as transições e quais geram aviso, com o caminho comum em seta grossa. As setas pontilhadas são mudanças sem aviso: acompanhe esses casos por GET /v1/submerchants/{merchantId}.

Correção de dados (status correcting)

Quando a análise pede correções, a subconta recebe o status correcting e o motivo vem no campo rejectionReason. A correção é feita no painel da Finvia, na gestão de subcontas, na área de correções pendentes. Depois do reenvio, a conta volta para análise (pending), sem aviso.
Para o negócio: se a sua plataforma cadastra vendedores por API, combine internamente quem vai fazer a correção no painel quando chegar um correcting. Pode ser o seu time de operações (com os dados enviados pelo vendedor) ou o próprio vendedor, se ele tiver acesso ao painel. Mostre ao vendedor o texto de rejectionReason, que descreve o que precisa ser corrigido.

Payload

O aviso é enviado por POST, sem envelope: o corpo é o próprio objeto de notificação, em camelCase. Não há nome de evento, id de evento nem marcação de teste.

Campos

date é a data de referência do status, e o valor depende de qual status chegou:

Regras de negócio

Passo a passo

O desenho abaixo mostra como tratar cada aviso de status no seu sistema.
Node.js
Para o desenvolvedor: como o aviso não tem assinatura, confirme o status em GET /v1/submerchants/{merchantId} antes de liberar a subconta. Quando chegar active, as chaves de API da subconta podem ser consultadas em Chaves de API da subconta.

Erros comuns

Perguntas frequentes

A documentação não define prazo. Acompanhe pelo aviso de status e, se precisar de previsão, consulte o seu contato na Finvia.
Sim. A volta para pending após o reenvio dos dados não gera aviso. O próximo aviso chega quando a análise mudar o status para pre_approved, correcting, active ou rejected.
Se a conta master tiver uma URL de aviso de status configurada, a subconta herdou essa URL. Para definir ou trocar a URL, peça ao suporte da Finvia. Enquanto isso, acompanhe o status por GET /v1/submerchants/{merchantId}.
Não necessariamente. A conta pode voltar para active com o desbloqueio, o que gera um novo aviso active.

Como testar

Veja também

Subcontas e KYC

Cadastro e análise das subcontas.

Criar subconta

Contrato completo, incluindo o postbackUrl.

Webhooks de saque

Avisos de saque das subcontas.

Webhooks: visão geral

Destinos, formatos, entrega e deduplicação.