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, a marca das páginas hospedadas (branding_settings), 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 Ativar organizaçã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.

Plano de taxas

fee_plan diz qual plano de taxas a organização paga em cada venda:

`fee_plan`	O que a organização paga	Quando você troca o plano padrão
`"default"`	O plano padrão atual da sua plataforma.	Passa a pagar o novo padrão na próxima cobrança.
`"plan_k6F3mqMZ"`	O plano fixado.	Nada muda.

Toda plataforma tem um plano padrão a partir da liberação das condições dela: nesse momento a Chargefy cria o plano Padrão, e depois você pode escolher outro plano como padrão no painel. Para trocar o plano de uma organização, envie fee_plan em POST /v1/organizations/{id}. O guia Planos de taxas das organizações filhas explica o processo completo.

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 organizações com o mesmo CPF/CNPJ no mesmo ambiente, 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. Enquanto o cadastro da organização não tem decisão (activation_status: "in_review"), payout_account pode vir null mesmo que o documento fiscal já tenha conta: ela aparece quando a organização é aprovada.

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": "[email protected]",
    "name": "Acme Ltda",
    "opening_date": "2015-08-01",
    "phone": "11999990000",
    "trade_name": "Acme"
  },
  "created_at": "2026-05-16T14:09:27Z",
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "[email protected]",
  "fee_plan": "default",
  "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": "[email protected]",
    "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",
  "support_label": null,
  "support_url": null,
  "terms_acceptance": {
    "accepted_at": "2026-05-16T14:11:40Z",
    "ip": "203.0.113.10",
    "user_agent": "Mozilla/5.0"
  },
  "terms_text": null,
  "terms_url": null,
  "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 recém-criada começa em not_submitted, mesmo que o CPF/CNPJ já tenha outro cadastro aprovado. O KYC é avaliado para esta organização e este ambiente; acompanhe requirements e envie o cadastro. Uma repetição do create pode devolver uma organização existente com o estado que ela já tinha.

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.

Mostrar 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.

Mostrar Campos de billing_address

string | null

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

object

Cores, fonte, tema e cantos da marca da organização — a identidade visual do checkout hospedado, da confirmação da compra, da fatura hospedada e do portal do cliente. Sempre presente e sempre preenchido: uma organização nova nasce com os padrões #000000, #5149EF, system, light e rounded. Logo principal, marca do rodapé e domínio próprio são configurados no Dashboard, em Configurações → Marca, e não aparecem na API. Quando a plataforma apresenta as vendas da organização com a própria marca, este objeto continua descrevendo a marca da organização — veja Marca e domínio próprio da plataforma.

Mostrar Campos de branding_settings

string

Cor de destaque em hex, #RGB ou #RRGGBB. Padrão #5149EF.

string

Perfil de cantos das páginas hospedadas: botões, campos, cards, menus, diálogos e badges. Radios e switches mantêm a forma. Padrão rounded.

Valor	Descrição
`pill`	Botões e campos em cápsula; cards, menus e diálogos ganham cantos proporcionais.
`rounded`	Cantos levemente arredondados, a escala padrão da Chargefy.
`sharp`	Cantos retos em tudo que é tematizável.

string

Cor principal da marca em hex, #RGB ou #RRGGBB. Padrão #000000.

string

Família tipográfica das páginas hospedadas. Padrão geist.

Valor	Descrição
`system`	Fonte padrão do sistema.
`inter`	Fonte Inter.
`geist`	Fonte Geist.
`instrument_sans`	Fonte Instrument Sans.
`manrope`	Fonte Manrope.
`plus_jakarta_sans`	Fonte Plus Jakarta Sans.
`dm_sans`	Fonte DM Sans.
`figtree`	Fonte Figtree.
`onest`	Fonte Onest.
`space_grotesk`	Fonte Space Grotesk.
`urbanist`	Fonte Urbanist.
`newsreader`	Fonte Newsreader.

string

Tema das páginas hospedadas. Padrão light.

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

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.

Mostrar 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.

Mostrar Campos de company

object | null

Endereço da empresa.

Mostrar Campos de address

string

Data de criação em ISO 8601.

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.

string

Plano de taxas que a organização paga. "default" quando ela segue o plano padrão da sua plataforma; o ID do plano (plan_*) quando um plano foi fixado. "default" corresponde ao plano com is_default: true em GET /v1/fee-plans.

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.

Mostrar 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.

Mostrar 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.

Mostrar 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 }.

Mostrar 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.

Mostrar 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.

Suporte e termos do vendedor

Essas informações pertencem à organização. Aparecem na fatura, no portal do cliente e no checkout quando checkout_experience.footer_expanded estiver habilitado. Os termos são exibidos sem exigir aceite do comprador e são independentes de terms_acceptance, que registra o aceite da organização ao ativar sua conta.

string | null

Texto do link de atendimento, até 80 caracteres. Sem rótulo, a página usa “Fale com o suporte”.

string | null

Link HTTP/HTTPS de atendimento, WhatsApp ou ajuda, até 2.048 caracteres.

string | null

Termos em texto simples, até 10.000 caracteres. Preencher este campo limpa terms_url.

string | null

Link HTTP/HTTPS dos termos, até 2.048 caracteres. Preencher este campo limpa terms_text.

Não envie terms_text e terms_url preenchidos na mesma requisição. Campos omitidos preservam o valor; envie null para limpar.

Visão geral

Ativação de organizações

Planos de taxas

Marca e domínio próprio

Modelo de negócio

Plano de taxas

Os blocos de cadastro

Data Object

Operações

Eventos

Suporte e termos do vendedor

​Plano de taxas

​Os blocos de cadastro

​Data Object

​Operações

​Eventos

​Suporte e termos do vendedor

Plano de taxas

Os blocos de cadastro

Data Object

Operações

Eventos

Suporte e termos do vendedor