Referência de organizações
Atualizar uma organização
Atualiza uma organização.
Atualiza campos públicos da organização e os blocos do cadastro financeiro (
Não envie
As cores voltam no formato em que foram salvas: quem enviou
Cada mudança de marca gera
O prefixo do
Os juros pertencem ao plano de taxas escolhido em
company, representative/individual com verification, business_profile, payout_account, terms_acceptance e statement_descriptor). A operação tem semântica de merge: apenas os campos enviados são modificados. A exceção é a aparência da marca (branding_settings.appearance), sempre enviada inteira.
Este é o endpoint de escrita da ativação por API: preencha os blocos, releia requirements.missing e, quando ele zerar, chame POST /v1/organizations/{id}/submit. O fluxo ponta a ponta está em Ativar organização por API.
platform, activation_status, activation_status_updated_at, activation_submitted_at, requirements, created_at e updated_at são somente leitura: enviá-los retorna 400.
document e document_type podem ser alterados apenas enquanto a organização ainda não tem identidade financeira viva: a ativação precisa estar em not_submitted ou disabled e a organização não pode ter nenhuma atividade de pagamento. Depois da primeira ativação ou movimentação, o documento identifica o histórico financeiro e se torna permanente. Veja o modelo completo em Reenviar KYC de uma organização.
Autenticação
A organização vem do
{id} da URL. Com chave de plataforma, não envie o
header Organization: a API valida se a organização do caminho tem uma
conexão ativa com a plataforma da chave.Parâmetros de caminho
Attributes
URL de file da Chargefy (
https://storage.chargefy.io/file_...) com purpose
organization_avatar, criada via POST /v1/files e pertencente à própria organização.
URLs externas são rejeitadas com 400. Use null para limpar.Conta para saques declarada para receber os repasses. Bloco atômico:
account_number, bank_code, routing_number e type são obrigatórios juntos. bank_name é opcional. Use null para limpar a declaração.O titular nunca é enviado: holder_name e document são derivados da identidade da organização e retornam 400 se aparecerem no corpo.Na escrita, payout_account declara a conta que será usada no envio do cadastro. Na leitura, o mesmo campo mostra a conta ativa do cadastro financeiro (objeto payout_account com pa_* e últimos 4 dígitos) — os dois lados só coincidem depois da aprovação. A conta é propriedade do documento fiscal: o novo valor passa a valer para as cobranças daquele CPF/CNPJ.Quando o documento fiscal da organização já tem uma conta para saques, payout_account não aparece em requirements.missing e a organização recebe nessa conta. Nesse caso não envie o bloco: declarar uma conta retorna 400 com code: "payout_account_not_accepted". Enviar null continua aceito.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. Aceita só a chave
appearance; qualquer outra, inclusive os campos removidos brand_color, accent_color, font_family, border_style e theme, retorna 400 parameter_unknown. Sem appearance, a marca não muda. O restante da organização continua com merge por campo, mas appearance é substituído inteiro. A logo das páginas é o avatar_url da organização, 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 ficam no Dashboard. A ativação e a revisão cadastral de uma organização filha usam sempre a marca da plataforma. Os quatro formatos aceitos estão em Marca.A nova aparência vale assim que é salva para todas as páginas que usam a marca da organização, inclusive links, faturas e sessões já enviados: cada página guarda de quem é a marca, não as cores, e lê a aparência atual ao abrir. A marca não tem modo: chave de teste e chave de produção alteram a mesma aparência. A cópia do botão (submit_type) não mora aqui — é definida por sessão.Perfil de negócio declarado. Merge por campo: enviar só
url mantém o annual_revenue guardado.mcc é somente leitura: a categoria do negócio é resolvida pela Chargefy a partir do registro público do CNPJ. Enviá-lo retorna 400.Dados cadastrais da empresa. Aceito apenas em organizações CNPJ; em organizações CPF retorna
400. Merge por campo.Em organizações CNPJ, estes campos são preenchidos automaticamente a partir do registro público do CNPJ logo após a criação; o que você grava sempre vence.Novo CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação. O documento é a identidade fiscal declarada da organização: ele define qual perfil financeiro a próxima activation session vai criar (pessoa física para CPF, pessoa jurídica para CNPJ).Só pode ser alterado enquanto
activation_status é not_submitted ou disabled e a organização não tem atividade de pagamento. A troca desativa o perfil financeiro reprovado anterior (se houver) e reinicia qualquer activation session aberta — chame POST /v1/activation-sessions novamente após a troca.Tipo do documento. Opcional: quando omitido, é derivado do
document. Quando enviado, precisa ser coerente com o número informado. Não pode ser enviado sem document.Plano de taxas que a organização paga:
- omitido: mantém o plano atual;
nullou"default": a organização recebe o plano padrão atual e permanece nele até outra atribuição;- ID de um plano da sua plataforma (
plan_*): a organização passa a usar esse plano até você trocar.
ch_live_...), porque o plano define o preço das
vendas reais da organização. Com chave de teste, omita o campo: enviar
fee_plan, mesmo null ou "default", retorna 400 com
code: "livemode_mismatch".A resposta traz o ID do plano atribuído. Veja os exemplos em
Plano de taxas.A pessoa física titular da organização. Aceito apenas em organizações CPF; em organizações CNPJ retorna
400. O CPF é o document da própria organização: individual.document não é aceito. Atualização parcial por campo: envie somente o que deseja alterar. Campos omitidos são preservados; null limpa cada dado pessoal ou o endereço. Nos campos de texto, string vazia também limpa. O bloco da pessoa e verification não aceitam null.Substitui a metadata da relação plataforma↔organização conectada. Disponível
apenas com API key de plataforma.
O representante legal da empresa. Aceito apenas em organizações CNPJ; em organizações CPF retorna
400. Atualização parcial por campo: envie somente o que deseja alterar. Campos omitidos são preservados; null limpa cada dado pessoal ou o endereço. Nos campos de texto, string vazia também limpa, exceto em representative.document. O bloco da pessoa e verification não aceitam null.Nome exibido na fatura do comprador. Normalizado para maiúsculas, sem acentos, apenas letras, números e espaços; precisa ficar entre 5 e 22 caracteres depois da normalização. Use
null para limpar.É propriedade do documento fiscal: o novo valor passa a valer para as cobranças daquele CPF/CNPJ. Depois do cadastro aprovado, a leitura devolve o valor em vigor no cadastro financeiro.Registro do aceite dos termos de serviço coletado por você. Bloco atômico; use
null para limpar.Suporte e termos do vendedor
Essas informações pertencem à organização. Aparecem na fatura, no portal do cliente e no checkout quandocheckout_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.
Texto do link de atendimento, até 80 caracteres. Sem rótulo, a página usa “Fale com o suporte”.
Link HTTP/HTTPS dos termos, até 2.048 caracteres. Preencher este campo limpa
terms_text.terms_text e terms_url preenchidos na mesma requisição. Campos omitidos preservam o valor; envie null para limpar.
Marca
A aparência vai embranding_settings.appearance: o bloco completo, com as seis chaves, ou null. Cada cor aceita três formas — nome, hex ou null —, e as duas podem ser diferentes no mesmo bloco. Não há atualização parcial dentro do bloco: para trocar só a cor do botão, releia a organização e reenvie as seis chaves com a cor nova. O guia Marca e aparência mostra o que cada campo pinta nas páginas.
(a) Cores pelo nome
Use uma das 18 cores quando quiser um tom pronto. O nome garante contraste entre o botão e o texto dele; as 17 paletas usam o mesmo tom nos dois temas, e só acarbon muda entre o claro e o escuro. Neste exemplo, o comprador vê o painel do produto e o botão Pagar em índigo, cantos bem arredondados (ellipse) e textos em Inter.
(b) Cores em hex
Use hex#RRGGBB para a cor exata da sua marca. O hex vale igual no tema claro e no escuro, e o texto do botão fica preto ou branco, o que tiver mais contraste. Neste exemplo, o painel do produto fica em #F6F9FC, o botão Pagar em verde #278629 com texto branco, e o Pix copia e cola aparece em Geist Mono.
"indigo" lê "indigo", quem enviou "#278629" lê "#278629". Nome e hex podem ser misturados no mesmo bloco.
(c) Sem cor de marca
Envienull nas duas cores para uma página só em tons de cinza. Botão e painel do produto usam o tom forte do cinza escolhido: quase preto em páginas claras, quase branco em escuras. Neste exemplo, com theme: "dark", o botão Pagar fica quase branco com texto escuro, em cantos retos (hexagon).
(d) Seguir a plataforma
Envieappearance: null. A aparência própria é apagada e as páginas da organização voltam a usar a da sua plataforma — e, se a plataforma não tiver uma, a padrão da Chargefy. Quando você muda a aparência da plataforma, as páginas dessa organização mudam junto. A resposta não mostra a aparência herdada: só o que a organização salvou.
organization.updated com o bloco anterior em previous_attributes.branding_settings. Veja o exemplo.
Erros da marca
Mensagens que a API devolve, literalmente:
Plano de taxas
A troca vale a partir da próxima cobrança da organização; cobranças já processadas não mudam. Cada troca geraorganization.updated com
previous_attributes.fee_plan. O guia
Planos de taxas das organizações filhas explica o plano
padrão e quando a taxa vale.
Sandbox e live têm cadastros separados. fee_plan define o preço das vendas
reais e só é aceito para o cadastro live, com chave de produção. Com chave de
teste, omita o campo e o plano atual do cadastro de teste é mantido.
(a) Fixar um plano
Envie o ID de um plano da sua plataforma. A organização paga esse plano mesmo que o padrão mude. Enviar o ID do plano que hoje é o padrão também fixa esse plano.(b) Usar o plano padrão atual
Envie"default" ou null. A organização recebe o plano padrão atual. Trocar o padrão depois não altera essa organização.
(c) Atualizar outros campos sem mexer no plano
Omitafee_plan. O plano atual é mantido.
Erros do plano de taxas
O
fee_plan é conferido antes de qualquer gravação: se ele for recusado, os
demais campos enviados na mesma chamada também não são gravados.
Exemplos completos de documento de identidade
Os exemplos abaixo usam uma organização CNPJ, por isso o bloco érepresentative.verification. Em uma organização CPF, envie exatamente o mesmo
conteúdo em individual.verification.
(a) CNH digital
Use o PDF oficial exportado do app CNH Digital emfront e omita back.
(b) CNH física, frente e verso
Use dois arquivos quando enviar fotos da CNH física.(c) RG, frente e verso
O RG sempre exige os dois lados em arquivos separados.(d) CREF completo
Use um único arquivo da carteira aberta, em imagem ou PDF, emfront.
(e) CREF, frente e verso
Use dois arquivos quando a carteira não estiver aberta em um único arquivo.(f) CIN digital
Use o PDF oficial exportado do app gov.br emfront e omita back.
(g) CIN física, frente e verso
Use dois arquivos quando enviar fotos da CIN física.(h) Passaporte
Use somente a página de identificação emfront; back não é aceito.
País e moeda
country e default_currency são só de leitura. Eles nascem com a
organização (hoje, BR e brl para todas) e não mudam pela API: enviar
qualquer um dos dois retorna 400 com code: "parameter_read_only" e o campo
em param, antes de qualquer gravação.
Resposta
200 OK com o objeto organization completo e já atualizado. A resposta direta não inclui diff.
Organização da própria plataforma
A organização dona da plataforma é atualizada pela mesma rota, com o mesmo contrato, para perfil (name, email, avatar_url, website, socials,
dados de cobrança, suporte e termos), marca (branding_settings) e
metadata. O cadastro financeiro e o preço dela não mudam pela API: document,
document_type, company, representative, individual,
business_profile, payout_account, terms_acceptance,
statement_descriptor e fee_plan respondem 400 com
code: "parameter_read_only" e o campo em param, antes de qualquer gravação.
400
Erros de acesso
Erros dos blocos de cadastro
Toda recusa de validação é400 com type: "invalid_request_error", code: "invalid_request" e param no caminho exato do campo. As mensagens abaixo são as que a API devolve, literalmente.
Bloco fora do tipo de documento
company
representative e individual
O prefixo do param acompanha o bloco enviado (representative em organizações CNPJ, individual em CPF).
verification
Um arquivo enviado pela API espera 30 dias pelo cadastro (
file.expires_at). Vencido, ele é recusado no campo que o aponta:
Duas recusas do bloco de verificação não trazem
param:
Arquivo não encontrado e arquivo de outra organização compartilham a mesma mensagem — a existência de arquivos de terceiros nunca é revelada.
O bloco
verification só entra em um cadastro aberto. Com a ativação em análise ou aprovada, enviá-lo responde 409:
Os demais blocos do cadastro continuam aceitos nesses estados.
business_profile
payout_account
Uma recusa deste bloco não é de formato e usa um
code próprio, para a sua integração tratar sem ler a mensagem:
terms_acceptance e statement_descriptor
Erros de troca de documento
Webhook
Quando a chamada altera campos visíveis para uma plataforma conectada, a Chargefy emiteorganization.updated para os endpoints da organização da plataforma.
data.object contém o snapshot completo atualizado. data.previous_attributes contém apenas os campos alterados e seus valores anteriores — quando requirements muda, o diff traz o objeto anterior completo. Em uma troca de documento após reprovação, a vinculação com o perfil financeiro reprovado é desativada: activation_status volta para not_submitted, requirements recomeça pelo missing do novo documento e statement_descriptor volta para null.
No webhook, o campo top-level
organization identifica a organização
conectada que mudou. Para reler o estado, use esse valor em GET /v1/organizations/{id}, sem header Organization.Tabela de juros do parcelamento
Disponível somente no Chargefy for Platforms, para operar suas organizações filhas.
fee_plan. Cada plano fixa uma tabela de juros na criação; várias combinações podem reutilizar a mesma tabela.
O campo installment_plan é somente leitura. Enviá-lo retorna 400 parameter_read_only em produção; com chave de teste, retorna 400 livemode_mismatch. Para trocar os juros de uma organização, escolha outro plano de taxas. A resposta mostra o plano e a tabela efetivos.
Escolher fee_plan: "default" ou null fixa o plano que é padrão naquele momento. Trocar o padrão depois não altera essa organização.
