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": null,
    "border_style": null,
    "brand_color": null,
    "font_family": null,
    "theme": null
  },
  "business_profile": null,
  "company": null,
  "created_at": "2026-05-16T14:09:27Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "contato@meusite.com",
  "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,
  "terms_acceptance": 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": "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_state_conflict",
    "message": "Platform is not active",
    "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 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, 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.

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

required

CPF (11 dígitos) ou CNPJ (14 dígitos) da organização conectada. Máscaras são aceitas e normalizadas para somente dígitos; qualquer outra quantidade de dígitos retorna 400. Este campo é a chave de idempotência dentro da plataforma.

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

required

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

Identidade visual inicial usada por invoices e pelo portal do cliente. O checkout hospedado é configurado separadamente no Checkout Builder.

Show Campos de branding_settings

string

Cor de destaque, hex #RGB ou #RRGGBB.

string

Estilo de borda de botões e campos.

Valor	Descrição
`pill`	Cantos totalmente arredondados.
`rounded`	Cantos levemente arredondados.
`sharp`	Cantos retos.

string

Cor de marca, hex #RGB ou #RRGGBB.

string

Família tipográfica da página hospedada.

Valor	Descrição
`system`	Fonte padrão do sistema.
`inter`	Fonte Inter.
`geist`	Fonte Geist.
`bitter`	Fonte Bitter.

string

Tema da página hospedada.

Valor	Descrição
`light`	Tema claro.
`dark`	Tema escuro.

string

E-mail principal da organização. Use null ou omita para vazio.

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.

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 → 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.) 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": null,
    "border_style": null,
    "brand_color": null,
    "font_family": null,
    "theme": null
  },
  "business_profile": null,
  "company": null,
  "created_at": "2026-05-16T14:09:27Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "contato@meusite.com",
  "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,
  "terms_acceptance": 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": "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_state_conflict",
    "message": "Platform is not active",
    "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`) ou header `Organization` enviado.
`401`	`authentication_failed`	API key ausente, inválida, revogada ou expirada.
`403`	`permission_denied`	Credencial não é uma API key de plataforma.
`409`	`resource_state_conflict`	Plataforma inativa ou configuração incompleta.
`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": null,
    "border_style": null,
    "brand_color": null,
    "font_family": null,
    "theme": null
  },
  "business_profile": null,
  "company": null,
  "created_at": "2026-05-16T14:09:27Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "contato@meusite.com",
  "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,
  "terms_acceptance": 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": "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_state_conflict",
    "message": "Platform is not active",
    "type": "invalid_request_error"
  }
}

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

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Criar uma organização

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Erros

Próximos passos

​Autenticação

​Attributes

​O que a Chargefy resolve sozinha

​Resposta

​Erros

​Próximos passos

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Erros

Próximos passos