Pular para o conteúdo principal
Cria uma organização conectada para a sua plataforma e devolve o objeto organization completo. O identificador retornado em id é o valor que você usa depois no header Organization para criar produtos, preços, checkout sessions, payment links, invoices e subscriptions em nome dessa organização. Só name e document são obrigatórios. Todo o resto tem default ou é resolvido pela Chargefy. Chamadas repetidas com o mesmo CPF/CNPJ dentro da mesma plataforma e ambiente retornam a organização já existente. O create não substitui campos de perfil de uma organização existente; use POST /v1/organizations/{id} para atualizar nome, email, marca ou metadata depois da criação. Uma organização excluída não é reaproveitada: cadastrar o mesmo documento depois de uma exclusão cria uma organização nova, com outro id. Vendas, clientes e catálogo da organização excluída permanecem no identificador antigo e não são transferidos.
Se a primeira chamada terminar em timeout ou 5xx, repita POST /v1/organizations com o mesmo documento. O documento funciona como chave de idempotência dentro da plataforma e do ambiente, então o retry devolve a mesma organização em vez de criar outra. Guarde também o X-Request-Id da resposta com erro para investigação.
O mesmo CNPJ criado com uma chave de teste e uma chave live recebe dois IDs org_* diferentes. Por exemplo, o cadastro feito com ch_test_... só pode ser usado em operações de teste; crie o cadastro live para operar em produção. Criar a organização não submete nem aprova o KYC. Uma organização excluída não é reutilizada por chamadas posteriores com o mesmo documento.

Autenticação

Requer API key de plataforma com escopo platform_admin.
Não envie o header Organization. A organização ainda está sendo criada e a API responde 400 se esse header estiver presente.
A organização criada já fica conectada à plataforma. Isso não significa que o cadastro financeiro está aprovado: consulte activation_status e requirements para saber se ela pode receber pagamentos.

Attributes

string
obrigatório
CPF (11 dígitos) ou CNPJ (14 dígitos) da organização conectada. Máscaras são aceitas e normalizadas para somente dígitos. O documento é conferido pelo dígito verificador: quantidade de dígitos diferente, sequência repetida ou dígito verificador incorreto retorna 400. Este campo é a chave de idempotência dentro da plataforma e do ambiente.
string
Tipo do documento. Quando omitido, inferimos pela quantidade de dígitos de document: 11 → cpf, 14 → cnpj. Se enviado, deve bater com o document — senão 400.
string
obrigatório
Nome público inicial da organização conectada.
string
URL de file da Chargefy (https://storage.chargefy.io/file_...) com purpose organization_avatar, criada via POST /v1/files. URLs externas são rejeitadas com 400. O file precisa pertencer à própria organização conectada, então o fluxo típico é criar a organização primeiro, subir o file com o header Organization e definir o avatar via update. Use null ou omita para vazio.
string
Informação adicional de cobrança. Use null ou omita para vazio.
object
Endereço de cobrança. Use null ou omita para vazio.
string
Nome usado em cobranças. Use null ou omita para vazio.
object
Marca inicial 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. Omitido, a organização nasce sem aparência própria (appearance: null) e usa a da sua plataforma. A logo das páginas é o avatar_url da organização; 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.
string
E-mail principal da organização. Use null ou omita para vazio.
string | null
Plano de taxas que a organização paga:
  • omitido, 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 usa 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
Mapa opcional string → string com até 50 chaves. A Chargefy só armazena e ecoa este objeto; use as chaves que fizerem sentido para o seu sistema. Chaves: [a-zA-Z0-9_\-.]{1,40}. Valores: até 500 caracteres.
array
Lista de redes sociais no formato { platform, url }. Padrão: []. Valores aceitos em platform:
string
Site público da organização. Use null ou omita para vazio.

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. O guia Marca e aparência mostra o que cada campo pinta nas páginas. A marca não tem modo: a mesma organização usa a mesma aparência em teste e em produção, com chave ch_test_... ou ch_live_.... Quando o mesmo documento já tem uma organização na sua plataforma e a API devolve a existente, a marca enviada não é aplicada; use POST /v1/organizations/{id}.

(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

Omita branding_settings, ou envie appearance: null. A organização nasce sem aparência própria e as páginas dela usam a aparência 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.

Erros da marca

Mensagens que a API devolve, literalmente:

Plano de taxas

Toda organização criada recebe o plano padrão atual da sua plataforma, a menos que você fixe outro plano em fee_plan. A tabela de juros vem do plano. Trocar o padrão depois não muda o plano de quem já existe; para trocar o de uma organização, use POST /v1/organizations/{id}. O guia Planos de taxas das organizações filhas explica o padrão e quando a taxa vale. Sandbox e live têm cadastros separados. fee_plan configura o preço das vendas reais e só é aceito com chave de produção. Com chave de teste, omita o campo: o cadastro de teste recebe o plano padrão. Para definir taxas live, crie ou atualize o cadastro live com a chave de produção. Repetir este create com o mesmo documento no mesmo ambiente não troca o plano.

(a) Usar o plano padrão atual

Omita fee_plan, ou envie null ou "default". A organização recebe o padrão atual. Trocar o padrão depois não altera essa organização.

(b) 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.

(c) Documento que já existe na plataforma

Quando o CPF/CNPJ já tem uma organização na sua plataforma, a API devolve essa organização com o plano que ela já tinha. O fee_plan enviado é validado (400 ou 404 se for inválido), mas não é aplicado. Para trocar o plano de uma organização existente, use POST /v1/organizations/{id}.

O que a Chargefy resolve sozinha

  • document é normalizado para somente dígitos e document_type é inferido pela quantidade de dígitos (11 → cpf, 14 → cnpj).
  • Mesmo documento na mesma plataforma e ambiente → retorna a organização conectada já existente, sem criar duplicata e sem sobrescrever o perfil dela.
  • O activation_status é resolvido automaticamente pela Chargefy. Uma organização nova nasce not_submitted, com requirements.missing listando tudo que o cadastro financeiro ainda precisa.
  • Os campos de perfil opcionais (email, branding_settings, socials, etc.) e o fee_plan só são aplicados quando a organização é criada de fato.
  • Sem branding_settings, a organização nasce com appearance: null e as páginas dela usam a aparência da sua plataforma.
  • country e default_currency nascem com a organização: hoje, BR e brl para todas. São só de leitura; enviar qualquer um dos dois retorna 400 com code: "parameter_read_only" e o campo em param, sem criar nada.
  • O webhook organization.created é emitido para a plataforma somente quando a organização é criada de fato — reuso idempotente não dispara webhook.

Resposta

200 OK com o objeto organization completo. Campos declarados nunca são omitidos; vazio vem como null, {} ou [].

Erros

Próximos passos

Depois de criar a organização, use o id retornado como header Organization nos endpoints que criam recursos em nome dela.
Para consultar ou atualizar a própria organização, coloque esse id na URL: GET /v1/organizations/{id} ou POST /v1/organizations/{id}. Nesses endpoints, não envie o header Organization.
Se a organização precisar completar cadastro financeiro, crie uma activation_session usando o id retornado. Ela devolve a URL hospedada para o vendedor concluir o fluxo.

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.