Skip to main content
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. 
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: 
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: 
{
  "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.

​
Quando criar uma nova sessão

organization.activation_statusComportamento recomendado
activation_pendingCrie a onboarding session normalmente.
pendingAguarde o próximo organization.updated; já existe análise em andamento.
activeNão crie nova sessão; a organização já está apta a operar.
disabledCrie 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}. Quando uma nova tentativa após disabled é enviada, a plataforma deve esperar uma transição como: 
{
  "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. 
curl -X GET "https://api.chargefy.io/v1/organizations/org_123" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}"
Resposta resumida: 
{
  "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 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.