Skip to main content
Para atualizar uma integração existente, comece pelo checklist de mudanças na integração de ativação.
Quando o cadastro financeiro de uma organização conectada é reprovado, a plataforma não recebe apenas um activation_status: "disabled". A organização carrega requirements: a lista de tarefas da ativação, que explica o que aconteceu, qual campo foi apontado e qual é o caminho de correção. Este guia mostra como consumir esse objeto de ponta a ponta.

​
Como o fluxo funciona

  1. A plataforma cria a organização conectada (POST /v1/organizations) e escolhe como coletar o cadastro: uma activation_session hospedada ou o formulário próprio descrito em Ativação por API.
  2. O vendedor preenche dados, documentos e conta para saques no canal escolhido. Ao concluir, a plataforma recebe organization.updated — isso significa “cadastro recebido”, não “aprovado”.
  3. O envio coloca a organização em activation_status: "in_review" (em análise), com requirements.pending_verification listando o que está sendo verificado. A análise é assíncrona e o resultado chega por organization.updated:
    • Aprovado → activation_status: "active" e requirements todo vazio.
    • Reprovado → activation_status: "disabled", requirements.errors com pelo menos um item e requirements.missing com o que é corrigível.
  4. Quando requirements.disabled_reason vem null, a plataforma corrige os campos apontados em missing e inicia uma nova tentativa na mesma organização (mesmo org_*). No hospedado, cria outra activation session; pela API, atualiza os campos e chama /submit novamente. A Chargefy substitui o perfil financeiro reprovado internamente — produtos, customers e histórico não se movem.
disabled não é um beco sem saída. Na maioria dos casos a reprovação é corrigível pelo próprio vendedor: nome divergente do CPF, documento ilegível, selfie ruim. requirements diz exatamente qual é o caso — e disabled_reason só vem preenchido quando não há caminho de correção.
activation_status: "disabled" não significa que a organização foi desconectada da plataforma. Continue usando o mesmo org_*, corrija o que requirements indicar e não crie outra organização para contornar a reprovação.

​
O objeto requirements

O campo organization.requirements está sempre presente e tem sempre o mesmo formato:
Cada activation_status preenche um lado do objeto: Regras de leitura:
  • requirements nunca é omitido. Quando não há pendência, todos os campos vêm vazios (null ou []).
  • activation_status: "disabled" garante pelo menos um item em errors.
  • Os caminhos pontuados usam representative.* em organizações CNPJ (o representante legal) e individual.* em organizações CPF; company.* só existe para CNPJ.
  • Se você receber um code que sua integração não conhece, exiba message e resolution — eles sempre vêm completos — e decida o fluxo por missing e disabled_reason, nunca pelo texto.
  • Os itens de errors são ordenados por code e deduplicados; múltiplos sinais da mesma natureza colapsam em um item só.

​
Tabela de códigos

O requirement de cada erro aponta o campo que falhou. Os valores abaixo usam o prefixo representative (CNPJ); em organizações CPF, o prefixo é individual. Em identity_name_mismatch, além do documento de verificação, missing também aponta representative.first_name e representative.last_name — o nome declarado precisa ser corrigido junto.
verification_failed é o código genérico: aparece quando a análise não detalhou um motivo específico. Nesse caso disabled_reason decide o caminho — quando vem "rejected.other", não abra nova tentativa automaticamente.

​
O que fazer em cada caso

​
disabled_reason: null — corrija e reenvie

  1. Mostre ao vendedor o que precisa ser corrigido: a resolution de cada erro, ou uma tradução sua a partir do code. Os caminhos em missing dizem exatamente o que recoletar.
  2. Inicie outra tentativa na mesma organização, usando o mesmo canal da sua integração.

​
Fluxo hospedado

Crie uma nova activation session:
Redirecione o vendedor para a url retornada. O fluxo hospedado reabre com os dados e arquivos ainda válidos da tentativa anterior preenchidos — o vendedor corrige apenas o que aparece em requirements.missing e reenvia. O item reprovado não é reutilizado. Por exemplo, em identity_document_mismatch o documento volta vazio, enquanto a selfie atual permanece visível e pode ser mantida ou substituída pelo vendedor.

​
Fluxo por API

Atualize somente os caminhos de requirements.missing com POST /v1/organizations/{id}. Omitir um arquivo preserva o atual; enviar outro file_* o substitui. Quando missing ficar vazio, chame POST /v1/organizations/{id}/submit novamente.
  1. Acompanhe o próximo organization.updated: a transição esperada é disabled → in_review (com errors limpo e pending_verification preenchido) e depois in_review → active ou uma nova reprovação.

​
disabled_reason preenchido — encaminhe ao suporte

Não há caminho de reenvio pela plataforma: Oriente o vendedor a falar com o suporte (ou abra o chamado em nome dele). Repetir a ativação com os mesmos dados não muda o resultado — não crie novas sessões em loop.

​
Variações de payload

​
(a) Aprovação

​
(b) Reprovação com pendência específica

O caso mais comum: um dado informado diverge do registro oficial. O code identifica o problema, requirement aponta o campo e a resolution diz exatamente o que corrigir — o vendedor resolve sozinho.

​
(c) Reprovação com múltiplas pendências

Documento e selfie reprovados na mesma análise. Cada pendência vira um item de errors; missing consolida os campos apontados. Resolva todas antes de reenviar. Os demais campos da organização seguem o formato completo de (b):

​
(d) Reprovação sem caminho de reenvio

Quando a análise não aprova o perfil e não há correção possível pelo vendedor, disabled_reason vem "rejected.other" e missing fica vazio:

​
(e) Motivo refinado, status inalterado

A análise pode detalhar o motivo depois da reprovação inicial. Chega um novo organization.updated em que só requirements muda — o objeto anterior completo vem no diff:

​
(f) Nova tentativa enviada após reprovação

Quando o vendedor reenvia a ativação, o status volta para in_review e as reprovações são limpas — pending_verification assume, e o requirements anterior aparece uma última vez no diff:

​
(g) Envio falhou antes da análise

Se o cadastro foi aceito pela API, mas a tentativa falhou antes de entrar na análise, chega um organization.updated levando a organização de volta para not_submitted. O erro e o campo a corrigir ficam em requirements; não é necessário fazer polling para descobrir essa volta.
Corrija os caminhos em missing e, no fluxo por API, chame /submit novamente. No fluxo hospedado, abra outra activation session para a mesma organização.

​
(h) Consulta direta

O mesmo estado está sempre disponível em GET /v1/organizations/{id}, em qualquer contexto de autenticação:

​
Limites e erros ao abrir nova tentativa

POST /v1/activation-sessions valida a elegibilidade da nova tentativa e pode responder:
O limite atual é de 3 tentativas de reativação por organização. Depois de esgotado, requirements.disabled_reason passa a "rejected.attempt_limit_reached", novas sessões respondem 409 activation_not_retryable e o caminho passa a ser o suporte — isso evita loops de reprovação com os mesmos dados. Reenvie apenas depois que o vendedor corrigiu o que os caminhos em missing apontam.

​
Boas práticas

  • Automatize por code, missing e disabled_reason, nunca pelo texto de message — os textos podem ser refinados sem aviso; os códigos e caminhos são estáveis.
  • Mostre resolution ao vendedor (ou uma tradução sua a partir do code). É a diferença entre “cadastro reprovado, procure o suporte” e “o nome informado não confere com o CPF — corrija e reenvie”.
  • Não crie sessões em loop. Reenvie apenas depois que o vendedor corrigiu algo. Reprovações repetidas com os mesmos dados terminam em activation_not_retryable.
  • Não invente motivo. Se code vier desconhecido para a sua integração, exiba os textos como estão e siga missing/disabled_reason.
  • A reprovação vale para o perfil financeiro, não para a organização: mantenha o mesmo org_*, produtos, customers e histórico. Veja reenviar KYC de uma organização.