Pular para o conteúdo principal
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. A organização dona da plataforma também é uma organização conectada a ela: aparece na lista, pode ser consultada e tem perfil, marca e metadata atualizáveis como qualquer outra. O cadastro financeiro, o plano de taxas, o envio para análise e a exclusão dela não são alterados pela API.
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:
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: 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: 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.*.
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_*.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.
string | null
Informação adicional de cobrança.
object | null
Endereço de cobrança. Vem null quando não foi informado.
string | null
Nome ou razão social usada em cobranças.
object
Marca da organização nas páginas do comprador — checkout, confirmação da compra, fatura hospedada e portal do cliente — e no botão dos e-mails enviados ao comprador. Sempre presente. Traz só o que a própria organização salvou: a aparência herdada da plataforma ou da Chargefy não aparece aqui. A logo das páginas é o avatar_url, a menos que outra logo (ou nenhuma) tenha sido escolhida no Dashboard; marca do rodapé, domínio próprio e a escolha de quem apresenta a venda são configurados só no Dashboard. O guia Marca e aparência mostra o que cada campo pinta.
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.
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.
string
País da conta, em código ISO 3166-1 de duas letras. Hoje toda organização é BR, porque o documento é CPF ou CNPJ. Só de leitura.
string
Data de criação em ISO 8601.
string
Moeda padrão da organização, em código ISO 4217 minúsculo: hoje, brl para todas. Vale quando uma request não informa currency, como ao criar um pagamento ou uma fatura. Só de leitura. Veja Moedas.
string | null
CPF ou CNPJ normalizado, apenas dígitos.
string | null
Tipo do documento da organização. Vem null quando não foi informado.
string | null
E-mail principal da organização.
string
ID do plano de taxas atribuído à organização (plan_*). Ele define taxas e juros. Trocar o padrão da plataforma não altera essa atribuição. Antes de um plano ser configurado, retorna "default".
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.
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 e motivos de bloqueio. Cada activation_status preenche um lado do objeto. Um bloqueio pode acrescentar disabled_reason em qualquer estado.
  • not_submitted → missing lista o que falta preencher antes do envio.
  • in_review → pending_verification lista o que está sendo verificado.
  • active → tarefas de ativação vazias.
  • 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.
array
Lista de redes sociais no formato { platform, url }.
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.
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.

Tabela de juros do parcelamento

Disponível somente no Chargefy for Platforms, para operar suas organizações filhas.
string
Tabela de juros do plano de taxas da organização filha, como "00299". Somente leitura: para mudar a tabela, atribua outro fee_plan. Sem plano configurado, "default" indica que ainda não há uma combinação atribuída. Cobranças já criadas mantêm seus valores.
Quem paga os juros é outra decisão, definida nas opções do pagamento. Escolha o plano de taxas.