> ## 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: reenviar KYC de uma organização > Como criar novas onboarding sessions para a mesma organização conectada sem mover produtos, customers ou histórico. Use uma `organization` como container operacional estável da conta conectada. Produtos, preços, customers, checkout sessions e histórico devem continuar vinculados ao mesmo `org_*`, mesmo quando os dados fiscais, KYC ou conta bancária precisarem mudar. ## Regra principal Crie a `organization` uma vez, guarde o `org_*` no seu sistema e crie onboarding sessions sempre com esse mesmo `organization_id`. ```bash theme={} curl -X POST "https://api.chargefy.io/v1/onboarding-sessions" \ -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "organization_id": "org_123", "return_url": "https://meusite.com/onboarding/return" }' ``` Se o perfil financeiro atual da organização não estiver apto, a Chargefy pode abrir uma nova tentativa de onboarding para a mesma organização. O novo perfil financeiro é gerenciado internamente pela Chargefy; a plataforma continua operando pelo mesmo `org_*`. ## Como a Chargefy modela documento e status Dois campos da `organization` parecem simétricos, mas seguem direções opostas: * **`document` é a identidade declarada.** Ele é informado na criação da organização e define qual cadastro financeiro a próxima onboarding session vai abrir: CPF abre o fluxo de pessoa física, CNPJ o de pessoa jurídica. O documento alimenta o cadastro — não é resultado dele. * **`activation_status` é derivado.** Ele reflete o estado do perfil financeiro mais recente: vai para `pending` quando um cadastro é enviado, `active` quando aprovado, `disabled` quando reprovado. A plataforma nunca escreve esse campo; ela o observa via `organization.updated`. Cada tentativa de onboarding materializa um **novo** perfil financeiro a partir do documento declarado. Tentativas anteriores (inclusive reprovadas) são registros históricos imutáveis — uma reprovação não é "editada", é substituída por uma nova tentativa. Por isso o caminho de retry é sempre: ajustar a declaração se preciso (documento) → abrir nova onboarding session → acompanhar o status derivado. Enquanto a organização não tem um perfil financeiro vivo, o documento é só declaração e pode ser corrigido. A partir da primeira ativação ou da primeira movimentação de pagamento, o documento passa a identificar o histórico financeiro daquela organização e se torna permanente. ## Trocar o documento antes de tentar de novo Caso comum: o cadastro com CNPJ foi reprovado e a conta quer tentar de novo como pessoa física (ou com outro CNPJ). Não crie outra organização — troque o documento declarado na mesma `organization` e abra uma nova onboarding session: ```bash theme={} curl -X POST "https://api.chargefy.io/v1/organizations/org_123" \ -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "document": "123.456.789-01" }' ``` A troca é aceita apenas quando **todas** as condições valem: * `activation_status` é `activation_pending` ou `disabled`; * não existe análise em andamento (`pending`); * a organização não tem nenhuma atividade de pagamento; * o novo documento não pertence a outra organização conectada da plataforma (nesse caso, use a organização existente — `409 document_already_in_use`). A troca desativa a vinculação com o perfil financeiro reprovado e reinicia qualquer onboarding session aberta. Depois dela, chame `POST /v1/onboarding-sessions` novamente: a mesma sessão (mesmo `os_*`) é reaproveitada e o wizard abre já no fluxo do novo documento. A plataforma recebe um `organization.updated` com o diff: ```json theme={} { "data": { "object": { "id": "org_123", "object": "organization", "activation_status": "disabled", "document": "12345678901", "document_type": "cpf" }, "previous_attributes": { "document": "12345678000190", "document_type": "cnpj" } }, "type": "organization.updated" } ``` Erros e condições completas em [Atualizar organização](/api-reference/organizations/update). ## Quando criar uma nova sessão | `organization.activation_status` | Comportamento recomendado | | -------------------------------- | ------------------------------------------------------------------------- | | `activation_pending` | Crie a onboarding session normalmente. | | `pending` | Aguarde o próximo `organization.updated`; já existe análise em andamento. | | `active` | Não crie nova sessão; a organização já está apta a operar. | | `disabled` | Crie uma nova onboarding session para a mesma organização. | `disabled` não é terminal para a organização. Ele significa que o perfil financeiro atual associado à organização não está apto a operar. A organização pode voltar para `pending` e depois `active` com uma nova tentativa de onboarding. ## Acompanhar resultado Escute estes eventos no endpoint da plataforma: * `organization.created` * `onboarding.session.submitted` * `organization.review.required` * `organization.review.submitted` * `organization.updated` `onboarding.session.submitted` confirma que a organização enviou o cadastro inicial. `organization.review.required` informa que uma atualização cadastral é necessária, e `organization.review.submitted` confirma o envio dessa atualização. Para saber se a organização pode transacionar, use `organization.updated` ou consulte [`GET /v1/organizations/{id}`](/api-reference/organizations/get). Quando uma nova tentativa após `disabled` é enviada, a plataforma deve esperar uma transição como: ```json theme={} { "data": { "object": { "id": "org_123", "object": "organization", "activation_status": "pending" }, "previous_attributes": { "activation_status": "disabled" } }, "type": "organization.updated" } ``` ## Exibir conta bancária Para exibir a conta bancária cadastrada no admin da plataforma, leia a `organization` conectada. A conta ativa aparece em `organization.bank_account`. ```bash theme={} curl -X GET "https://api.chargefy.io/v1/organizations/org_123" \ -H "Authorization: Bearer {{PLATFORM_API_KEY}}" ``` Resposta resumida: ```json theme={} { "id": "org_123", "object": "organization", "activation_status": "active", "bank_account": { "id": "ba_123", "object": "bank_account", "account_number_last4": "1940", "bank_code": "336", "bank_name": "Banco C6", "created_at": "2026-05-16T14:09:27Z", "holder_name": "Acme Ltda", "is_active": true, "is_verified": false, "livemode": true, "metadata": {}, "routing_number": "0001", "type": "checking", "updated_at": "2026-05-16T14:20:00Z" } } ``` Esse mesmo objeto também chega em `data.object.bank_account` no webhook `organization.updated` quando a conta conectada da organização muda. A Chargefy nunca retorna o número completo da conta; use `bank_name`, `routing_number` e `account_number_last4` para exibição. Se a plataforma precisar consultar uma conta específica por `ba_*` ou listar contas conectadas à organização, use os endpoints de [`bank_accounts`](/api-reference/bank-accounts/object) com o header `Organization: org_123`. ## O que não fazer * Não crie uma nova `organization` só porque um KYC foi reprovado — nem mesmo quando a conta vai tentar com outro documento; troque o `document` na mesma organização. * Não mova produtos, customers, preços ou histórico para outro `org_*`. * Não dependa de dados internos da infraestrutura financeira; use apenas o objeto `organization` público. * Não tente trocar o documento de uma organização ativa ou com histórico de pagamentos; a partir daí o documento é permanente e o caminho é criar uma nova organização.