Skip to main content
Uma organization representa a entidade que opera dentro da Chargefy — a sua própria empresa usando a API diretamente, ou uma organização conectada da sua plataforma. Nela ficam a identidade pública, os dados fiscais, o endereço de cobrança, os padrões visuais do checkout hospedado e, em contexto de plataforma, o status financeiro da organização conectada. A organization é o centro de escopo da API: produtos, preços, customers, checkout sessions, payment links, invoices e subscriptions pertencem à organização que está atuando. Uma API key de organização enxerga a própria organização; uma API key de plataforma usa o header Organization para escolher qual organização conectada está vendendo. Os webhooks carregam essa organização no envelope do evento — em fan-out para plataformas, apontando para a organização conectada que originou a mudança. Plataformas criam organizações conectadas com POST /v1/organizations. Se a organização também precisa completar cadastro financeiro, crie uma onboarding_session usando o organization; ela devolve a URL hospedada para o vendedor concluir o fluxo.

​
Data Object

Este é o formato completo retornado em create, get, update, itens de list e em data.object dos webhooks organization.*. 
{
  "id": "org_123",
  "object": "organization",
  "activation_status": "active",
  "activation_status_updated_at": "2026-05-16T14:20:00Z",
  "avatar_url": "https://storage.chargefy.io/file_NtkQ6yYhdBJrXlcw",
  "bank_account": {
    "id": "ba_123",
    "object": "bank_account",
    "account_number_last4": "5678",
    "bank_code": "001",
    "bank_name": "Banco Exemplo S.A.",
    "created_at": "2026-05-16T14:09:27Z",
    "holder_name": "Acme Ltda",
    "is_active": true,
    "is_verified": false,
    "livemode": true,
    "metadata": {},
    "routing_number": "0001",
    "type": "checking",
    "updated_at": "2026-05-16T14:20:00Z"
  },
  "billing_additional_info": null,
  "billing_address": {
    "city": "São Paulo",
    "country": "BR",
    "line1": "Av. Paulista, 1000",
    "line2": null,
    "postal_code": "01310-100",
    "state": "SP"
  },
  "billing_name": "Acme Ltda",
  "branding_settings": {
    "accent_color": "#FF6B00",
    "border_style": "rounded",
    "brand_color": "#1B1B1B",
    "font_family": "system",
    "theme": "light"
  },
  "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": [
    {
      "platform": "instagram",
      "url": "https://instagram.com/meusite"
    }
  ],
  "updated_at": "2026-05-16T14:20:00Z",
  "website": "https://meusite.com"
}
​
id
string
Identificador público da organização. Usa o prefixo org_*.
​
object
string
Sempre "organization".
​
activation_status
string | null
Status financeiro da organização conectada: activation_pending, pending, active ou disabled. Fora de contexto de plataforma, vem null. disabled significa que o perfil financeiro atual não está apto; a organização pode iniciar uma nova tentativa de onboarding sem trocar de org_*.
​
activation_status_updated_at
string | null
Quando activation_status foi atualizado pela última vez.
​
avatar_url
string | null
URL pública do logo ou avatar, servida como file da Chargefy (https://storage.chargefy.io/file_...).
​
bank_account
object | null
Conta bancária ativa conectada à organização. É o campo recomendado para plataformas exibirem a conta cadastrada no admin do parceiro. Nunca inclui o número completo da conta; use account_number_last4 para identificação.
​
billing_additional_info
string | null
Informação adicional de cobrança.
​
billing_address
object | null
Endereço de cobrança. Vem null quando não foi informado.
​
billing_name
string | null
Nome ou razão social usada em cobranças.
​
branding_settings
object
Padrões visuais usados pela experiência hospedada da organização. Campos não configurados vêm como null e a página hospedada aplica o padrão do sistema.
​
created_at
string
Data de criação em ISO 8601.
​
document
string | null
CPF ou CNPJ normalizado, apenas dígitos.
​
document_type
string | null
Tipo do documento: cpf, cnpj ou null.
​
email
string | null
E-mail principal da organização.
​
livemode
boolean
true em produção; false em ambiente de teste.
​
metadata
object
Metadata da relação plataforma↔organização conectada. Fora de contexto de plataforma, retorna {}.
​
name
string
Nome público da organização.
​
platform
string | null
ID da plataforma quando a leitura acontece em contexto de plataforma. Fora desse contexto, vem null.
​
socials
array
Lista de redes sociais no formato { platform, url }.
​
updated_at
string | null
Data da última atualização em ISO 8601.
​
website
string | null
Site público da organização.

​
Operações

​
Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook: O payload sempre carrega o objeto organization completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados.