Skip to main content
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_123",
  "object": "organization",
  "activation_status": "activation_pending",
  "activation_status_updated_at": null,
  "avatar_url": null,
  "bank_account": 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
  },
  "created_at": "2026-05-16T14:09:27Z",
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "contato@meusite.com",
  "livemode": true,
  "metadata": {},
  "name": "Acme Ltda",
  "platform": "plat_456",
  "socials": [],
  "updated_at": "2026-05-16T14:09:27Z",
  "website": "https://meusite.com"
}
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. 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.

​
Autenticação

Requer API key de plataforma com escopo platform_admin. O header Organization não é aceito neste endpoint, porque a organização ainda está sendo criada.

​
Attributes

​
document
string
required
CPF ou CNPJ da organização conectada. Máscaras são aceitas e normalizadas para somente dígitos. Este campo é a chave de idempotência dentro da plataforma.
​
document_type
string
cpf ou cnpj. Quando omitido, inferimos pelo comprimento de document. Se enviado, deve bater com a quantidade de dígitos de document.
​
name
string
required
Nome público inicial da organização conectada.
​
avatar_url
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.
​
billing_additional_info
string
Informação adicional de cobrança. Use null ou omita para vazio.
​
billing_address
object
Endereço de cobrança. Use null ou omita para vazio.
​
billing_name
string
Nome usado em cobranças. Use null ou omita para vazio.
​
branding_settings
object
Identidade visual inicial aplicada ao checkout hospedado da organização.
​
email
string
E-mail principal da organização. Use null ou omita para vazio.
​
metadata
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.
​
socials
array
Lista de redes sociais no formato { platform, url }. platform: x, github, facebook, instagram, youtube, linkedin ou other.
​
website
string
Site público da organização. Use null ou omita para vazio.
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_123",
  "object": "organization",
  "activation_status": "activation_pending",
  "activation_status_updated_at": null,
  "avatar_url": null,
  "bank_account": 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
  },
  "created_at": "2026-05-16T14:09:27Z",
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "contato@meusite.com",
  "livemode": true,
  "metadata": {},
  "name": "Acme Ltda",
  "platform": "plat_456",
  "socials": [],
  "updated_at": "2026-05-16T14:09:27Z",
  "website": "https://meusite.com"
}

​
Erros

StatusQuando
400Payload inválido (document, document_type, name, metadata) ou header Organization enviado.
401API key ausente, inválida, revogada ou expirada.
403Credencial não é uma API key de plataforma.
409Plataforma inativa ou setup da plataforma incompleto.
503Erro 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. Se a organização precisar completar cadastro financeiro, crie uma onboarding_session usando o id retornado. Ela devolve a URL hospedada para o vendedor concluir o fluxo.