Organizações

Na API pública, uma organization representa uma organização conectada da sua plataforma. Nela ficam a identidade pública, os dados fiscais, o endereço de cobrança, os padrões visuais do checkout hospedado, o status financeiro (activation_status) e a lista de tarefas da ativação (requirements), que mostra o que falta preencher, o que está em análise e o que foi reprovado. O recurso organizations é exclusivo do Chargefy for Platforms. Somente uma API key de plataforma com escopo platform_admin pode criar, listar, consultar, atualizar ou enviar organizações conectadas para análise. Uma API key de organização padrão não acessa esse recurso; ela atua diretamente nos recursos da própria conta, como produtos, customers e pagamentos.

No recurso organizations, autentique com a API key de plataforma, use a coleção ou o {id} da URL e não envie o header Organization. Em produtos, customers, checkouts, pagamentos e outros recursos pertencentes à conta conectada, envie o org_* no header Organization.

Os webhooks carregam a organização de contexto no campo top-level organization. Para eventos enviados à plataforma, esse campo aponta para a organização conectada que originou a mudança, não para a organização da plataforma.

Conexão ativa e ativação financeira são estados diferentes. Uma organização pode estar conectada à plataforma e continuar acessível pela API com activation_status: "not_submitted", "in_review" ou "disabled". Somente "active" indica que ela está apta a receber pagamentos.

Plataformas criam organizações conectadas com POST /v1/organizations. Para o cadastro financeiro existem dois caminhos, que escrevem na mesma ficha:

Hospedado — crie uma activation_session usando o organization; ela devolve a URL hospedada para o vendedor concluir o fluxo.
Por API — preencha os blocos de cadastro com POST /v1/organizations/{id} e envie para análise com POST /v1/organizations/{id}/submit. O passo a passo está em Ativação por API.

Trate o org_* como identificador estável no seu sistema. Corrija e reenvie o cadastro na mesma organização; não crie outra organização para contornar uma reprovação financeira.

Os blocos de cadastro

Além do perfil público, a organização guarda o cadastro financeiro declarado:

Bloco	O que é	Existe em
`company`	Dados cadastrais da empresa.	Organizações CNPJ.
`representative`	O representante legal da empresa.	Organizações CNPJ.
`individual`	A pessoa física titular.	Organizações CPF.
`business_profile`	Faturamento declarado, site e categoria do negócio.	Todas.
`payout_account`	Conta que recebe os repasses.	Todas.
`terms_acceptance`	Registro do aceite dos termos.	Todas.
`statement_descriptor`	Nome exibido na fatura do comprador.	Todas.

Duas regras de visibilidade valem para a leitura:

Dados de empresa são públicos. company vem do registro público do CNPJ e aparece em qualquer organização daquele documento, tenha ela preenchido o cadastro ou não.
Dados de pessoa física são privados. individual, representative e business_profile só aparecem para quem os cadastrou: eles vivem na organização que os coletou, e uma organização criada por outra plataforma para o mesmo documento lê esses blocos como null.

As fotos de verificação nunca aparecem em nenhuma leitura: documento e selfie são enviados por referência de arquivo na escrita e o progresso é reportado só por requirements. payout_account e statement_descriptor são propriedades do documento fiscal: são compartilhados por todas as organizações com o mesmo CPF/CNPJ, e alterá-los redefine o padrão de recebimento e o nome na fatura para as cobranças daquele documento. A conta é sempre mascarada — o número completo nunca é retornado.

Data Object

Este é o formato completo retornado em create, get, update, itens de list e em data.object dos webhooks organization.*.

{
  "id": "org_8JxLXKvSTSnHz7s8",
  "object": "organization",
  "activation_status": "active",
  "activation_status_updated_at": "2026-05-16T14:20:00Z",
  "activation_submitted_at": "2026-05-16T14:12:00Z",
  "avatar_url": "https://storage.chargefy.io/file_b56ezKLwiPpNP7mQ",
  "billing_additional_info": "Inscrição municipal 123456",
  "billing_address": {
    "city": "São Paulo",
    "country": "BR",
    "line1": "Av. Paulista, 1000",
    "line2": "Conjunto 101",
    "postal_code": "01310-100",
    "state": "SP"
  },
  "billing_name": "Acme Ltda",
  "branding_settings": {
    "accent_color": "#FF6B00",
    "border_style": "rounded",
    "brand_color": "#1B1B1B",
    "font_family": "system",
    "theme": "light"
  },
  "business_profile": {
    "annual_revenue": {
      "amount": 50000000,
      "currency": "brl"
    },
    "mcc": "5734",
    "url": "https://meusite.com"
  },
  "company": {
    "address": {
      "city": "São Paulo",
      "line1": "Avenida Paulista",
      "line2": "Conjunto 101",
      "neighborhood": "Bela Vista",
      "number": "1000",
      "postal_code": "01310100",
      "state": "SP"
    },
    "email": "contato@meusite.com",
    "name": "Acme Ltda",
    "opening_date": "2015-08-01",
    "phone": "11999990000",
    "trade_name": "Acme"
  },
  "created_at": "2026-05-16T14:09:27Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "contato@meusite.com",
  "individual": null,
  "livemode": true,
  "metadata": {},
  "name": "Acme Ltda",
  "payout_account": {
    "id": "pa_8gqQH2RWZi27y1sZ",
    "object": "payout_account",
    "account_number_last4": "5678",
    "bank_code": "001",
    "bank_name": "Banco Exemplo S.A.",
    "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"
  },
  "platform": "plat_1aGVVLipZK7V2fQF",
  "representative": {
    "address": {
      "city": "São Paulo",
      "line1": "Rua das Flores",
      "line2": null,
      "neighborhood": "Jardins",
      "number": "50",
      "postal_code": "01410000",
      "state": "SP"
    },
    "birthdate": "1990-04-12",
    "document": "12345678901",
    "email": "nome@email.com",
    "first_name": "Ana",
    "last_name": "Souza",
    "phone": "11988887777"
  },
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [],
    "pending_verification": []
  },
  "socials": [
    {
      "platform": "instagram",
      "url": "https://instagram.com/meusite"
    }
  ],
  "statement_descriptor": "ACME LTDA",
  "terms_acceptance": {
    "accepted_at": "2026-05-16T14:11:40Z",
    "ip": "203.0.113.10",
    "user_agent": "Mozilla/5.0"
  },
  "updated_at": "2026-05-16T14:20:00Z",
  "website": "https://meusite.com"
}

string

Identificador público da organização. Usa o prefixo org_*.

string

Sempre "organization".

string

Status financeiro da organização. Sempre presente, em qualquer contexto de autenticação. Em disabled, requirements explica o motivo e o que fazer — a organização pode iniciar uma nova tentativa de ativação sem trocar de org_*.

Valor	Descrição
`not_submitted`	O cadastro financeiro ainda não foi enviado para análise.
`in_review`	Cadastro enviado e em análise.
`active`	Perfil financeiro aprovado e apto a receber pagamentos.
`disabled`	O perfil financeiro atual não está apto. Veja `requirements`.

Uma organização pode nascer active com requirements.missing vazio e activation_submitted_at: null: o CPF/CNPJ dela já tinha um cadastro aprovado, e o status é do documento. Nesse caso não há nada a preencher nem a enviar — trate como apta.

string | null

Quando activation_status foi atualizado pela última vez.

string | null

Quando o cadastro financeiro foi enviado para análise pela última vez. Vem null antes do primeiro envio.

string | null

URL pública do logo ou avatar, servida como file da Chargefy (https://storage.chargefy.io/file_...).

object | null

Conta para saques principal conectada à organização. É o campo recomendado para plataformas exibirem a conta cadastrada no admin do parceiro. Nunca inclui o número completo da conta; use account_number_last4 para identificação. Ser a conta principal não garante o crédito dos repasses: a organização deve conferir os recebimentos no extrato bancário.

Show Campos de payout_account

string

Tipo da conta para saques.

Valor	Descrição
`checking`	Conta corrente.
`savings`	Conta poupança.

string | null

Informação adicional de cobrança.

object | null

Endereço de cobrança. Vem null quando não foi informado.

Show Campos de billing_address

string | null

Nome ou razão social usada em cobranças.

object

Padrões visuais usados por invoices e pelo portal do cliente. Campos não configurados vêm como null. O checkout hospedado usa o Checkout Builder.

Show Campos de branding_settings

string | null

Família tipográfica da página hospedada. Vem null quando não configurado.

Valor	Descrição
`system`	Fonte padrão do sistema.
`inter`	Fonte Inter.
`geist`	Fonte Geist.
`bitter`	Fonte Bitter.

string | null

Tema da página hospedada. Vem null quando não configurado.

Valor	Descrição
`light`	Tema claro.
`dark`	Tema escuro.

string | null

Estilo de borda de botões e campos. Vem null quando não configurado.

Valor	Descrição
`pill`	Cantos totalmente arredondados.
`rounded`	Cantos levemente arredondados.
`sharp`	Cantos retos.

object | null

Perfil de negócio declarado da organização. Vem null até algum dado existir, e também quando a leitura vem de uma organização que não declarou esses dados.

Show Campos de business_profile

object | null

Faturamento anual declarado: amount em centavos e currency.

string | null

Categoria do negócio (MCC), resolvida pelo perfil financeiro. Somente leitura.

string | null

Site ou página declarada do negócio.

object | null

Dados cadastrais da empresa. Só existe em organizações CNPJ; vem null até algum dado ser coletado. É informação pública do registro do CNPJ: aparece em qualquer organização daquele documento.

Show Campos de company

object | null

Endereço da empresa.

Show Campos de address

string

Data de criação em ISO 8601.

object

Preferências de exibição do Dashboard da Chargefy.

Show dashboard_settings

string

Identificador IANA (ex.: America/Sao_Paulo) usado para exibir datas e horários no Dashboard, para toda a equipe da organização. Não participa de cobrança: vencimentos, ciclos de assinatura, jobs, webhooks e todos os timestamps da API são instantes absolutos em UTC.

string | null

CPF ou CNPJ normalizado, apenas dígitos.

string | null

Tipo do documento da organização. Vem null quando não foi informado.

Valor	Descrição
`cpf`	Pessoa física.
`cnpj`	Pessoa jurídica.

string | null

E-mail principal da organização.

object | null

A pessoa física titular de uma organização CPF. Vem null em organizações CNPJ, antes da coleta, ou quando a leitura vem de uma organização que não cadastrou essa pessoa. document é o próprio CPF da organização. Fotos de verificação nunca aparecem aqui — o progresso é reportado em requirements.

Show Campos de individual

boolean

true em produção; false em ambiente de teste.

object

Metadata da relação entre a plataforma autenticada e a organização conectada. Retorna {} quando vazia.

string

Nome público da organização.

string | null

ID da plataforma vinculada à organização conectada. Nas operações públicas de organizations, identifica a plataforma autenticada.

object | null

O representante legal de uma organização CNPJ. Vem null em organizações CPF, antes da coleta, ou quando a leitura vem de uma organização que não cadastrou essa pessoa. Mesmo formato de individual; aqui document é o CPF do representante. Fotos de verificação nunca aparecem aqui — o progresso é reportado em requirements.

object

Lista de tarefas da ativação financeira. Sempre presente; em organização active, todos os campos vêm vazios. Cada activation_status preenche um lado do objeto:

not_submitted → missing lista o que falta preencher antes do envio.
in_review → pending_verification lista o que está sendo verificado.
active → tudo vazio.
disabled → errors traz as reprovações, missing traz o que é corrigível e disabled_reason marca os casos terminais.

O fluxo completo de leitura, os códigos e exemplos de cada variação estão no guia Requisitos de ativação.

Show Campos de requirements

string | null

Motivo terminal da reprovação. null quando há caminho de correção.

Valor	Descrição
`rejected.attempt_limit_reached`	Limite de tentativas esgotado; encaminhe ao suporte.
`rejected.other`	Sem caminho de reenvio; encaminhe ao suporte.

array

Reprovações da última análise. Vazio fora de disabled. Itens ordenados por code e deduplicados.

Show Campos de errors[]

string

Código estável da reprovação. Ao receber um code desconhecido, use message e resolution para exibição.

Valor	Descrição
`identity_name_mismatch`	O nome informado não confere com o registrado para o CPF/CNPJ.
`identity_document_mismatch`	O documento de identidade não pertence ao titular informado.
`identity_document_verification_failed`	O documento de identidade não pôde ser verificado.
`selfie_verification_failed`	A selfie não passou na verificação.
`payout_account_verification_failed`	A conta para saques informada não pôde ser verificada.
`business_activity_not_supported`	A atividade econômica registrada não é aceita.
`registration_data_inconsistent`	Os dados cadastrais divergem dos registros oficiais.
`identity_verification_failed`	A verificação de identidade não foi aprovada.
`verification_failed`	O perfil financeiro não pôde ser aprovado.

string

Descrição em inglês do que aconteceu. Estável para log e exibição.

string

Caminho pontuado do campo apontado pela reprovação, como representative.verification.document ou payout_account.

string

Instrução em inglês de como resolver, pronta para exibir ao usuário final ou traduzir a partir do code.

array

Caminhos pontuados do que falta preencher ou corrigir antes de enviar (ou reenviar) o cadastro. Ordenados alfabeticamente.

array

Caminhos pontuados do que está em verificação durante a análise.

array

Lista de redes sociais no formato { platform, url }.

Show Campos de socials[]

string

Rede social do perfil.

Valor	Descrição
`x`	Perfil no X.
`github`	Perfil no GitHub.
`facebook`	Perfil no Facebook.
`instagram`	Perfil no Instagram.
`youtube`	Canal no YouTube.
`linkedin`	Perfil no LinkedIn.
`other`	Outra rede ou site.

string

URL pública do perfil.

string | null

Nome exibido na fatura do comprador. É propriedade do documento fiscal e é compartilhado entre organizações com o mesmo CPF/CNPJ. Vem null enquanto não houver valor declarado nem cadastro enviado.

object | null

Registro do aceite dos termos de serviço. Vem null antes do aceite.

Show Campos de terms_acceptance

string | null

Data da última atualização em ISO 8601.

string | null

Site público da organização.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos, exclusivos de endpoints com events_from: "platform":

Os eventos organization.* são entregues somente às plataformas conectadas; endpoints com events_from: "organization" não podem assiná-los. organization.created e organization.updated carregam o objeto organization completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados. Os eventos organization.review.* carregam o objeto da solicitação de revisão e usam o campo top-level organization para identificar a conta conectada.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Os blocos de cadastro

Data Object

Operações

Eventos

​Os blocos de cadastro

​Data Object

​Operações

​Eventos

Os blocos de cadastro

Data Object

Operações

Eventos