Criar uma organização

curl -X POST "https://api.chargefy.io/v1/organizations" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12.345.678/0001-90",
    "name": "Acme Ltda"
  }'

{
  "id": "org_H92JKT6WFfc83e3j",
  "object": "organization",
  "activation_status": "not_submitted",
  "activation_status_updated_at": null,
  "activation_submitted_at": null,
  "avatar_url": null,
  "billing_additional_info": null,
  "billing_address": null,
  "billing_name": null,
  "branding_settings": {
    "accent_color": "#5149EF",
    "border_style": "rounded",
    "brand_color": "#000000",
    "font_family": "system",
    "theme": "light"
  },
  "business_profile": null,
  "company": null,
  "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": null,
  "platform": "plat_n9h4B8EwD1Q6d9uH",
  "representative": null,
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "business_profile.annual_revenue",
      "company.address",
      "company.email",
      "company.name",
      "company.opening_date",
      "company.phone",
      "representative.address",
      "representative.birthdate",
      "representative.document",
      "representative.email",
      "representative.first_name",
      "representative.last_name",
      "representative.phone",
      "representative.verification.document",
      "representative.verification.selfie",
      "statement_descriptor",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  },
  "socials": [],
  "statement_descriptor": null,
  "support_label": null,
  "support_url": null,
  "terms_acceptance": null,
  "terms_text": null,
  "terms_url": null,
  "updated_at": "2026-05-16T14:09:27Z",
  "website": "https://meusite.com"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Organization header is not accepted when creating an organization",
    "param": "Organization",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "livemode_mismatch",
    "message": "fee_plan changes the price of live sales and can only be set with a live API key. In test mode, omit fee_plan.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Unauthorized — invalid api key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "permission_denied",
    "message": "Only platform API keys can create organizations",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "No fee plan with this ID exists for your platform.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Platform is not active",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "fee_plan_incompatible",
    "message": "The organization's receiving model is incompatible with this fee plan.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Failed to load organization",
    "type": "api_error"
  }
}

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, branding ou metadata depois da criação.

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.

Valor	Descrição
`cpf`	Pessoa física.
`cnpj`	Pessoa jurídica.

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: cores, fonte, tema e cantos usados por todas as páginas hospedadas dela — checkout, confirmação da compra, fatura hospedada e portal do cliente. Cada campo omitido nasce com o padrão, e a organização criada já devolve os cinco preenchidos. 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. A ativação e a revisão cadastral de uma organização filha usam sempre a marca da plataforma; veja Marca e domínio próprio da plataforma.

Mostrar Campos de branding_settings

string

Cor de destaque, 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, 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.

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 segue o plano padrão da sua plataforma e acompanha as trocas de padrã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 "default" ou o ID do plano. 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:

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

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.

Plano de taxas

Toda organização criada segue o plano padrão da sua plataforma, a menos que você fixe outro plano em fee_plan. A escolha pode ser trocada depois com 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 segue 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) Seguir o plano padrão

Omita fee_plan, ou envie null ou "default". Quando você trocar o plano padrão, a organização passa a pagar o novo padrão na próxima cobrança.

curl -X POST "https://api.chargefy.io/v1/organizations" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12.345.678/0001-90",
    "name": "Acme Ltda"
  }'

{
  "id": "org_H92JKT6WFfc83e3j",
  "object": "organization",
  "...": "demais campos da organization",
  "fee_plan": "default"
}

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

curl -X POST "https://api.chargefy.io/v1/organizations" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12.345.678/0001-90",
    "fee_plan": "plan_k6F3mqMZ",
    "name": "Acme Ltda"
  }'

{
  "id": "org_H92JKT6WFfc83e3j",
  "object": "organization",
  "...": "demais campos da organization",
  "fee_plan": "plan_k6F3mqMZ"
}

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

{
  "id": "org_H92JKT6WFfc83e3j",
  "object": "organization",
  "...": "demais campos da organization",
  "fee_plan": "default"
}

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.
O webhook organization.created é emitido para a plataforma somente quando a organização é criada de fato — reuso idempotente não dispara webhook.

curl -X POST "https://api.chargefy.io/v1/organizations" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12.345.678/0001-90",
    "name": "Acme Ltda"
  }'

Resposta

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

{
  "id": "org_H92JKT6WFfc83e3j",
  "object": "organization",
  "activation_status": "not_submitted",
  "activation_status_updated_at": null,
  "activation_submitted_at": null,
  "avatar_url": null,
  "billing_additional_info": null,
  "billing_address": null,
  "billing_name": null,
  "branding_settings": {
    "accent_color": "#5149EF",
    "border_style": "rounded",
    "brand_color": "#000000",
    "font_family": "system",
    "theme": "light"
  },
  "business_profile": null,
  "company": null,
  "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": null,
  "platform": "plat_n9h4B8EwD1Q6d9uH",
  "representative": null,
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "business_profile.annual_revenue",
      "company.address",
      "company.email",
      "company.name",
      "company.opening_date",
      "company.phone",
      "representative.address",
      "representative.birthdate",
      "representative.document",
      "representative.email",
      "representative.first_name",
      "representative.last_name",
      "representative.phone",
      "representative.verification.document",
      "representative.verification.selfie",
      "statement_descriptor",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  },
  "socials": [],
  "statement_descriptor": null,
  "support_label": null,
  "support_url": null,
  "terms_acceptance": null,
  "terms_text": null,
  "terms_url": null,
  "updated_at": "2026-05-16T14:09:27Z",
  "website": "https://meusite.com"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Organization header is not accepted when creating an organization",
    "param": "Organization",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "livemode_mismatch",
    "message": "fee_plan changes the price of live sales and can only be set with a live API key. In test mode, omit fee_plan.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Unauthorized — invalid api key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "permission_denied",
    "message": "Only platform API keys can create organizations",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "No fee plan with this ID exists for your platform.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Platform is not active",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "fee_plan_incompatible",
    "message": "The organization's receiving model is incompatible with this fee plan.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Failed to load organization",
    "type": "api_error"
  }
}

Erros

Status	`code`	Quando
`400`	`invalid_request`	Payload inválido (`document`, `document_type`, `name`, `metadata`, `fee_plan`) ou header `Organization` enviado. Em `fee_plan`, vale para valor que não é `null`, `"default"` nem um ID no formato `plan_*`, com `param: "fee_plan"`.
`400`	`livemode_mismatch`	`fee_plan` enviado com chave de teste (`ch_test_...`), em qualquer forma: ID, `null` ou `"default"`. Vem com `param: "fee_plan"` e nada é gravado. Em teste, omita o campo.
`401`	`authentication_failed`	API key ausente, inválida, revogada ou expirada.
`403`	`permission_denied`	Credencial não é uma API key de plataforma.
`404`	`resource_missing`	`fee_plan` aponta para um plano que não existe na sua plataforma (`param: "fee_plan"`).
`409`	`resource_state_conflict`	Plataforma inativa ou configuração incompleta.
`422`	`fee_plan_incompatible`	O recebimento já definido para o CPF/CNPJ da organização é diferente do recebimento dos planos da sua plataforma. Com `fee_plan` enviado, vem com `param: "fee_plan"`; sem ele, sem `param`, porque a incompatibilidade é da própria organização. Fale com o suporte.
`500`	`internal_error`	A API não conseguiu montar a resposta final; a organização pode já ter sido persistida. Repita com o mesmo documento e use o `org_*` retornado.
`503`	`internal_error`	Erro temporário resolvendo a organização. Faça retry.

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.

curl -X POST "https://api.chargefy.io/v1/organizations" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12.345.678/0001-90",
    "name": "Acme Ltda"
  }'

{
  "id": "org_H92JKT6WFfc83e3j",
  "object": "organization",
  "activation_status": "not_submitted",
  "activation_status_updated_at": null,
  "activation_submitted_at": null,
  "avatar_url": null,
  "billing_additional_info": null,
  "billing_address": null,
  "billing_name": null,
  "branding_settings": {
    "accent_color": "#5149EF",
    "border_style": "rounded",
    "brand_color": "#000000",
    "font_family": "system",
    "theme": "light"
  },
  "business_profile": null,
  "company": null,
  "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": null,
  "platform": "plat_n9h4B8EwD1Q6d9uH",
  "representative": null,
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "business_profile.annual_revenue",
      "company.address",
      "company.email",
      "company.name",
      "company.opening_date",
      "company.phone",
      "representative.address",
      "representative.birthdate",
      "representative.document",
      "representative.email",
      "representative.first_name",
      "representative.last_name",
      "representative.phone",
      "representative.verification.document",
      "representative.verification.selfie",
      "statement_descriptor",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  },
  "socials": [],
  "statement_descriptor": null,
  "support_label": null,
  "support_url": null,
  "terms_acceptance": null,
  "terms_text": null,
  "terms_url": null,
  "updated_at": "2026-05-16T14:09:27Z",
  "website": "https://meusite.com"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Organization header is not accepted when creating an organization",
    "param": "Organization",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "livemode_mismatch",
    "message": "fee_plan changes the price of live sales and can only be set with a live API key. In test mode, omit fee_plan.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Unauthorized — invalid api key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "permission_denied",
    "message": "Only platform API keys can create organizations",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "No fee plan with this ID exists for your platform.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Platform is not active",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "fee_plan_incompatible",
    "message": "The organization's receiving model is incompatible with this fee plan.",
    "param": "fee_plan",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Failed to load organization",
    "type": "api_error"
  }
}

Visão geral

Ativação de organizações

Planos de taxas

Marca e domínio próprio

Modelo de negócio

Criar uma organização

Autenticação

Attributes

Suporte e termos do vendedor

Plano de taxas

(a) Seguir o plano padrão

(b) Fixar um plano

(c) Documento que já existe na plataforma

O que a Chargefy resolve sozinha

Resposta

Erros

Próximos passos

​Autenticação

​Attributes

​Suporte e termos do vendedor

​Plano de taxas

​(a) Seguir o plano padrão

​(b) Fixar um plano

​(c) Documento que já existe na plataforma

​O que a Chargefy resolve sozinha

​Resposta

​Erros

​Próximos passos

Autenticação

Attributes

Suporte e termos do vendedor

Plano de taxas

(a) Seguir o plano padrão

(b) Fixar um plano

(c) Documento que já existe na plataforma

O que a Chargefy resolve sozinha

Resposta

Erros

Próximos passos