Pular para o conteúdo principal
Atualiza campos públicos da organização e os blocos do cadastro financeiro (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.
O ID da URL sempre prevalece. Um header Organization diferente não troca o alvo da atualização. Para evitar atualizar a conta errada, não envie esse header nesta rota.

Parâmetros de caminho

string
obrigatório
ID da organização.

Attributes

string
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.
object
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.
string
Informação adicional de cobrança. Use null para limpar.
object
Endereço de cobrança. Use null para limpar.
string
Nome usado em cobranças. Use null para limpar.
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. 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.
object
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.
object
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.
string
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.
string
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.
string
E-mail principal. Use null para limpar.
string | null
Plano de taxas que a organização paga:
  • omitido: mantém o plano atual;
  • null ou "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.
Exige chave de produção (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.
object
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.
object
Substitui a metadata da relação plataforma↔organização conectada. Disponível apenas com API key de plataforma.
Use metadata para guardar referências do seu sistema na relação entre a plataforma autenticada e a organização conectada.
string
Nome público da organização. Não aceita string vazia.
object
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.
array
Substitui a lista inteira de redes sociais. Use [] para limpar.
string
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.
object | null
Registro do aceite dos termos de serviço coletado por você. Bloco atômico; use null para limpar.
string
Site público. 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 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.

Marca

A aparência vai em branding_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ó a carbon 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.
As cores voltam no formato em que foram salvas: quem enviou "indigo" lê "indigo", quem enviou "#278629" lê "#278629". Nome e hex podem ser misturados no mesmo bloco.

(c) Sem cor de marca

Envie null 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

Envie appearance: 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.
Cada mudança de marca gera 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 gera organization.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

Omita fee_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 em front 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, em front.

(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 em front 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 em front; 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 emite organization.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.
Os juros pertencem ao plano de taxas escolhido em 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.