> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Plataformas: guia completo de sessões de ativação
> O que é uma sessão de ativação, como criar, o que o vendedor vê, quais eventos esperar e como tratar cada resultado — do primeiro POST até a conta apta a receber.
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](/platforms/activation-integration-changes).
**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.
| Antes | Agora |
| --------------------------------------- | ---------------------------------- |
| `onboarding_session` | `activation_session` |
| `os_*` | `as_*` |
| `POST/GET /v1/onboarding-sessions` | `POST/GET /v1/activation-sessions` |
| `/onboarding/os_*` | `/activation/as_*` |
| `onboarding_session_id` na `return_url` | `activation_session` |
| `organization_id` na `return_url` | `organization` |
| evento específico da sessão | `organization.updated` |
## 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`](/api-reference/organizations/object).
## Os três objetos do fluxo
| Objeto | O que é | Tempo de vida |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `organization` | A conta do vendedor na Chargefy. Guarda o `org_*` no seu sistema — produtos, clientes, vendas e o **status financeiro** vivem nela. | Permanente. |
| `activation_session` | Uma tentativa de cadastro: o link hospedado + o estado do preenchimento. | Enquanto estiver aberta, recebe URLs novas sem trocar o `as_*`. Uma nova tentativa recebe outro `as_*`. |
| `organization.requirements` | A lista de tarefas da ativação: o que falta preencher, o que está em análise e, na reprovação, o que corrigir. | Vive na organization; sempre presente, vazio quando não há pendência. |
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](/platforms/connected-organizations).
## Passo a passo
### 1. Crie (ou reaproveite) a organização conectada
```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations" \
-H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"document": "12.345.678/0001-90",
"name": "Acme Ltda"
}'
```
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:
```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
-H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"organization": "org_MWWLzPLjNU2YuBZ3",
"return_url": "https://meusite.com/activation/return"
}'
```
```json theme={"theme":"css-variables"}
{
"id": "as_QD3KYp7C7fqJZ54K",
"object": "activation_session",
"created_at": "2026-04-30T18:30:00Z",
"expires_at": "2026-04-30T18:31:00Z",
"livemode": true,
"metadata": {},
"opened_at": null,
"organization": "org_MWWLzPLjNU2YuBZ3",
"platform": "plat_xzF6wE4VTNdq68Hu",
"return_url": "https://meusite.com/activation/return",
"status": "created",
"updated_at": "2026-04-30T18:30:00Z",
"url": "https://hosted.chargefy.io/activation/as_QD3KYp7C7fqJZ54K?authorization_code={{AUTHORIZATION_CODE}}"
}
```
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](/api-reference/activation-sessions/create).
### 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:
| Parâmetro | Valor |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `activation_session` | ID `as_*` da sessão que originou o retorno. |
| `organization` | ID `org_*` da organização, quando já resolvido. |
| `status` | `submitted` quando o formulário foi aceito para processamento; `cancelled` quando o usuário saiu antes do envio. |
**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`](/api-reference/webhooks/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`](/api-reference/webhooks/organization.updated):
**Aprovado** — libere os recebimentos:
```json theme={"theme":"css-variables"}
{
"data": {
"object": {
"id": "org_MWWLzPLjNU2YuBZ3",
"object": "organization",
"activation_status": "active",
"activation_status_updated_at": "2026-05-16T14:09:27Z",
"activation_submitted_at": "2026-05-16T14:05:00Z",
"avatar_url": null,
"billing_additional_info": null,
"billing_address": null,
"billing_name": null,
"branding_settings": {
"accent_color": null,
"border_style": null,
"brand_color": null,
"font_family": null,
"theme": null
},
"business_profile": {
"annual_revenue": {
"amount": 30000000,
"currency": "brl"
},
"mcc": "5734",
"url": "https://empresa.com.br"
},
"company": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Rua Exemplo, 100",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"email": "contato@empresa.com.br",
"name": "Minha Empresa Ltda",
"opening_date": "2019-06-01",
"phone": "+5511999990000",
"trade_name": "Minha Empresa"
},
"created_at": "2026-05-16T14:09:27Z",
"dashboard_settings": {
"timezone": "America/Sao_Paulo"
},
"document": "12345678000195",
"document_type": "cnpj",
"email": "contato@empresa.com.br",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Minha Empresa",
"payout_account": null,
"platform": "plat_xzF6wE4VTNdq68Hu",
"representative": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Rua Exemplo, 100",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"birthdate": "1990-04-12",
"document": "12345678901",
"email": "ana@empresa.com.br",
"first_name": "Ana",
"last_name": "Souza",
"phone": "+5511988887777"
},
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": []
},
"socials": [],
"statement_descriptor": "MINHA EMPRESA",
"terms_acceptance": {
"accepted_at": "2026-05-16T14:04:30Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
},
"updated_at": "2026-05-16T14:09:27Z",
"website": null
},
"previous_attributes": {
"activation_status": "in_review",
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": [
"payout_account",
"representative.verification.document",
"representative.verification.selfie"
]
}
}
},
"type": "organization.updated"
}
```
**Reprovado** — mostre o motivo e o caminho:
```json theme={"theme":"css-variables"}
{
"data": {
"object": {
"id": "org_MWWLzPLjNU2YuBZ3",
"object": "organization",
"activation_status": "disabled",
"activation_status_updated_at": "2026-05-16T14:09:27Z",
"activation_submitted_at": "2026-05-16T14:05:00Z",
"avatar_url": null,
"billing_additional_info": null,
"billing_address": null,
"billing_name": null,
"branding_settings": {
"accent_color": null,
"border_style": null,
"brand_color": null,
"font_family": null,
"theme": null
},
"business_profile": {
"annual_revenue": {
"amount": 30000000,
"currency": "brl"
},
"mcc": "5734",
"url": "https://empresa.com.br"
},
"company": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Rua Exemplo, 100",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"email": "contato@empresa.com.br",
"name": "Minha Empresa Ltda",
"opening_date": "2019-06-01",
"phone": "+5511999990000",
"trade_name": "Minha Empresa"
},
"created_at": "2026-05-16T14:09:27Z",
"dashboard_settings": {
"timezone": "America/Sao_Paulo"
},
"document": "12345678000195",
"document_type": "cnpj",
"email": "contato@empresa.com.br",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Minha Empresa",
"payout_account": null,
"platform": "plat_xzF6wE4VTNdq68Hu",
"representative": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Rua Exemplo, 100",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"birthdate": "1990-04-12",
"document": "12345678901",
"email": "ana@empresa.com.br",
"first_name": "Ana",
"last_name": "Souza",
"phone": "+5511988887777"
},
"requirements": {
"disabled_reason": null,
"errors": [
{
"code": "identity_name_mismatch",
"message": "The name provided does not match the name registered for the taxpayer id.",
"requirement": "representative.verification.document",
"resolution": "Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt."
}
],
"missing": [
"representative.first_name",
"representative.last_name",
"representative.verification.document"
],
"pending_verification": []
},
"socials": [],
"statement_descriptor": "MINHA EMPRESA",
"terms_acceptance": {
"accepted_at": "2026-05-16T14:04:30Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
},
"updated_at": "2026-05-16T14:09:27Z",
"website": null
},
"previous_attributes": {
"activation_status": "in_review",
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": [
"representative.verification.document",
"representative.verification.selfie"
]
}
}
},
"type": "organization.updated"
}
```
### 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](/platforms/resolve-activation-rejections).
## O ciclo de vida da sessão
| `status` | O que significa | O que a plataforma faz |
| ------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `created` | Sessão criada; o link ainda não foi aberto. | Nada — aguarde ou reemita a URL se o vendedor perdeu o redirect. |
| `in_progress` | O vendedor abriu e está preenchendo. O progresso é salvo automaticamente. | Nada. Se ele sair no meio, um novo `POST` emite outra URL e ele continua de onde parou. |
| `submitted` | O formulário foi enviado. A sessão não muda mais. | Passe a acompanhar a `organization`; a sessão não informa aprovação ou reprovação. |
Consulta pontual: [`GET /v1/activation-sessions/{id}`](/api-reference/activation-sessions/get)
— ú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
| Evento | O que significa | Ação recomendada |
| --------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------ |
| `organization.created` | Organização conectada criada. | Vincule o `org_*` ao seu registro. |
| `organization.updated` (`activation_status: "in_review"`) | Cadastro recebido; análise em andamento. | Mostre "Em análise". Não libere recebimentos. |
| `organization.updated` (`activation_status: "active"`) | Cadastro aprovado. | Libere recebimentos. |
| `organization.updated` (`activation_status: "disabled"`) | Cadastro não aprovado. | Leia `requirements` para oferecer correção ou suporte. |
| `organization.updated` (só `requirements` no diff) | As pendências foram atualizadas. | Atualize a orientação mostrada ao vendedor. |
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](/api-reference/events/types).
## Erros do create que o seu código deve tratar
| HTTP | `code` | Quando acontece | O que fazer |
| ---- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 409 | `organization_already_active` | A organização já está apta. | Não crie sessão; esconda o CTA de ativação. |
| 409 | `organization_activation_in_review` | Já existe análise em andamento. | Mostre "em análise" e aguarde o webhook. |
| 409 | `activation_not_retryable` | `requirements.disabled_reason` está preenchido: não há caminho de reenvio, ou o limite de tentativas de reativação (atualmente 3) foi atingido. | Encaminhe ao suporte. |
| 409 | `document_already_in_use` | O documento pertence a outro cadastro financeiro. | Suporte, ou [troque o documento](/platforms/resubmit-organization-verification#trocar-o-documento-antes-de-tentar-de-novo). |
| 422 | `organization_document_required` | A organização não tem CPF/CNPJ válido. | Atualize o `document` da organização antes de criar a sessão. |
## 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](/platforms/resubmit-organization-verification).
**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](/platforms/activate-by-api#modo-de-teste).
**Preciso guardar o `as_*`?**
Só se quiser correlacionar eventos ou depurar. O identificador que o seu
sistema precisa guardar é o `org_*`.
## Referências
* Objeto e operações: [`activation_session`](/api-reference/activation-sessions/object) · [create](/api-reference/activation-sessions/create) · [get](/api-reference/activation-sessions/get)
* Resultado e pendências: [`organization`](/api-reference/organizations/object) · [Requisitos de ativação](/platforms/resolve-activation-rejections)
* Eventos: [`organization.updated`](/api-reference/webhooks/organization.updated) · [tipos de eventos](/api-reference/events/types)
* Contexto de plataforma: [organizações conectadas](/platforms/connected-organizations) · [reenviar KYC](/platforms/resubmit-organization-verification)