Skip to main content
Este guia explica o fluxo de ativação financeira de ponta a ponta, na ordem em que ele acontece de verdade. Ele foi escrito para o time de produto e engenharia de uma plataforma: o que cada objeto significa, o que fazer em cada momento, o que mostrar para o seu vendedor e o que esperar da Chargefy.
Já integra este fluxo? Revise o checklist de mudanças na integração de ativação.
Mudança de contrato em 25 de julho de 2026: esta superfície passou a se chamar Activation Sessions. Não há alias para os nomes anteriores; gere URLs novas depois da atualização.

​
O que é uma sessão de ativação

Para receber pagamentos, todo vendedor precisa de um cadastro financeiro aprovado: dados pessoais ou da empresa, documento de identidade, selfie e conta para saques, tudo verificado. Construir esse formulário — com upload de documentos, validações e regras regulatórias que mudam — é caro e não é o core da sua plataforma. Uma activation_session resolve isso: é um link temporário para uma página hospedada pela Chargefy onde o seu vendedor preenche o cadastro completo. Você cria a sessão pela API, redireciona o vendedor para a url retornada, e a Chargefy cuida do formulário, dos uploads, da coleta da conta para saques e do envio para análise. Quando termina, o vendedor volta para o seu produto pela return_url. Três coisas que a palavra “session” não significa aqui:
  • Não é um login. É uma autorização temporária, de uso único, embutida na URL.
  • Não é permanente. A URL expira em 60 segundos se não for aberta; gerar outra é um novo POST (barato e idempotente).
  • Não é onde o resultado mora. A sessão termina quando o cadastro é enviado. Aprovação e reprovação chegam depois, pela organization.

​
Os três objetos do fluxo

A regra de ouro: o org_* é o identificador estável. Cadastro reprovado, documento trocado, nova tentativa — nada disso muda o org_*, e nada do que você construiu em cima dele (produtos, integrações, histórico) se perde.

​
Pré-requisitos

  1. Sua plataforma ativa e com o setup concluído (sem isso, o create responde 409).
  2. Uma API key de plataforma (Authorization: Bearer {{PLATFORM_API_KEY}}).
  3. Um endpoint de webhook registrado — o resultado da ativação chega por evento, não por polling.
  4. A organização conectada criada com documento (CPF ou CNPJ). O documento define se o fluxo abre como pessoa física ou jurídica.
Se você ainda não cria organizações conectadas, comece por Plataformas: organizações conectadas.

​
Passo a passo

​
1. Crie (ou reaproveite) a organização conectada

Guarde o id (org_*). Chamadas repetidas com o mesmo documento retornam a mesma organização — sem duplicatas.

​
2. Crie a sessão de ativação

Só dois campos são obrigatórios:
Detalhes que importam para o produto:
  • Enquanto a sessão estiver aberta, o ID não muda. Repetir o POST para uma sessão created ou in_progress devolve o mesmo as_* com uma URL nova.
  • Uma nova tentativa recebe um novo ID. Depois de submitted, a sessão anterior não é reaberta. Se a organização puder reenviar o cadastro, o próximo POST cria outro as_*. O org_* continua sendo o mesmo.
  • A url vale 60 segundos e é de uso único. Ela foi feita para redirect imediato, não para mandar por e-mail. Se o vendedor demorar, gere outra com um novo POST.
  • metadata é seu campo de correlação (string → string, até 50 chaves). Ele volta na consulta da sessão — útil para ligar a sessão ao seu registro interno.
Contrato completo: Criar uma sessão de ativação.

​
3. Redirecione o vendedor

Envie o vendedor para a url imediatamente após criar a sessão (redirect no navegador dele). No fluxo hospedado ele vai:
  1. Confirmar os dados pessoais ou da empresa (o documento já vem do cadastro da organização);
  2. Descrever a atividade do negócio;
  3. Fotografar/enviar o documento de identidade e uma selfie;
  4. Informar a conta para saques que vai receber os repasses;
  5. Revisar e enviar.
Tudo isso é da Chargefy: você não coleta, não armazena e não transporta nenhum documento ou dado bancário.

​
4. O vendedor volta pela return_url

Quando ele conclui (ou abandona) o fluxo, volta para a sua return_url. A Chargefy preserva os parâmetros que já existiam na URL e acrescenta: O retorno não é a aprovação. Mesmo status=submitted informa apenas que o cadastro entrou em processamento. A tela de retorno certa é neutra: “Recebemos seu cadastro” ou “Continue seu cadastro”, decidida pelo estado real (webhook ou um GET /v1/organizations/{id}).

​
5. Chega o organization.updated de análise

Quando o vendedor envia o cadastro, a organização passa para análise e seu endpoint recebe um organization.updated com activation_status: "in_review". O que está sendo verificado aparece em requirements.pending_verification.
in_review significa “cadastro recebido”, não “aprovado”. No seu produto, o estado certo aqui é “em análise”. Não libere recebimentos por este evento.

​
6. Chega o resultado, pela organization

A análise é assíncrona (minutos, às vezes mais). O veredito chega por organization.updated: Aprovado — libere os recebimentos:
Reprovado — mostre o motivo e o caminho:

​
7. Reprovou? Corrija e reenvie — sem drama

disabled não é fim de linha. requirements diz o que aconteceu e o que fazer: cada item de errors traz o motivo (code, message), o campo apontado (requirement) e a instrução (resolution); missing consolida os caminhos que precisam ser corrigidos; disabled_reason marca os casos terminais.
  • disabled_reason: null → há caminho de correção. Mostre a instrução ao vendedor (os caminhos em missing dizem o que recoletar) e chame POST /v1/activation-sessions de novo para o mesmo org_*. A Chargefy cria uma nova sessão, com outro as_*, e reaproveita os dados já salvos para que o vendedor corrija apenas o necessário. A nova página abre diretamente na etapa relacionada à reprovação. Arquivos ainda válidos permanecem no formulário: se apenas o documento foi recusado, por exemplo, a selfie atual continua visível e pode ser mantida, removida ou substituída. Removê-la torna o novo envio obrigatório antes da revisão.
  • disabled_reason preenchido → o caso é terminal: "rejected.attempt_limit_reached" significa limite de tentativas esgotado; "rejected.other" significa que não há caminho de reenvio. Nos dois casos, encaminhe ao suporte e não repita a ativação em loop.
A tabela completa de códigos, todas as variações de payload e os limites de tentativa estão em Requisitos de ativação.

​
O ciclo de vida da sessão

Consulta pontual: GET /v1/activation-sessions/{id} — útil para depurar, mas o dia a dia é orientado por webhook. No GET, url e expires_at voltam null de propósito: URL só nasce no POST.

​
Como acompanhar o resultado

Todos os eventos carregam o objeto completo em data.object e apenas os campos alterados em data.previous_attributes. Processe por id do evento (idempotência) e trate código de pendência desconhecido de forma genérica — o conjunto cresce. Catálogo completo: Tipos de eventos.

​
Erros do create que o seu código deve tratar

​
Boas práticas de produto

  • Um botão, uma chamada. “Ativar recebimentos” → POST → redirect. A idempotência elimina a necessidade de gerenciar estado de sessão do seu lado.
  • Estados visíveis no seu admin: não iniciado (not_submitted), em análise (in_review), ativo (active), pendência (disabled + requirements). São os quatro estados de activation_status — não invente um quinto.
  • Na reprovação, mostre o motivo, não um beco. “Cadastro reprovado, procure o suporte” queima conversão; “o nome informado não confere com o CPF — corrija e reenvie” resolve na hora. Use resolution (ou traduza pelo code).
  • Notifique o vendedor quando organization.updated chegar — aprovado ou reprovado, é ele quem precisa agir ou comemorar.
  • Use metadata para correlação, nunca para lógica: a Chargefy só ecoa.

​
O que não fazer

  • Não crie outra organization porque um cadastro reprovou. O retry é sempre no mesmo org_* — criar outra conta espalha o histórico do vendedor.
  • Não trate o retorno à return_url como aprovação (nem como envio).
  • Não faça polling da sessão para saber o resultado — o resultado nem fica nela; escute organization.updated.
  • Não guarde nem reenvie a url — expira em 60 segundos; emita outra na hora do clique.
  • Não crie sessões em loop após reprovação sem o vendedor corrigir algo: tentativas repetidas com os mesmos dados terminam em activation_not_retryable.

​
Perguntas frequentes

O vendedor fechou a aba no meio. Perdeu tudo? Não. O progresso fica salvo na sessão. Um novo POST /v1/activation-sessions emite outra URL e o fluxo reabre onde parou. Quanto tempo demora a análise? Normalmente minutos, mas é assíncrona por natureza. Modele o estado “em análise” como parte normal do funil, não como erro. Posso mandar a URL por e-mail/WhatsApp? Não como está — ela expira em 60 segundos. O padrão certo: o link do seu e-mail aponta para o seu produto, que cria a sessão na hora do clique e redireciona. O vendedor errou o CPF/CNPJ. E agora? Enquanto a organização não está ativa e não tem pagamentos, troque o document com POST /v1/organizations/{id} e crie uma nova sessão — mesmo org_*, sem perder nada. Veja reenviar KYC de uma organização. Sessão em ambiente de teste? Funciona. Com credencial de teste, a análise é simulada e o desfecho é escolhido pelo CPF/CNPJ da organização — a tabela está em Ativação por API. Preciso guardar o as_*? Só se quiser correlacionar eventos ou depurar. O identificador que o seu sistema precisa guardar é o org_*.

​
Referências