Atualizar uma organização

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "branding_settings": {
      "accent_color": "#FF6B00",
      "border_style": "rounded",
      "brand_color": "#1B1B1B",
      "theme": "light"
    },
    "email": "financeiro@meusite.com",
    "metadata": {},
    "name": "Acme Brasil Ltda"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile": {
      "annual_revenue": {
        "amount": 120000000,
        "currency": "brl"
      },
      "url": "https://meusite.com"
    },
    "company": {
      "address": {
        "city": "São Paulo",
        "line1": "Avenida Paulista",
        "line2": "Conjunto 101",
        "neighborhood": "Bela Vista",
        "number": "1000",
        "postal_code": "01310100",
        "state": "SP"
      },
      "email": "financeiro@meusite.com",
      "name": "ACME COMERCIO LTDA",
      "opening_date": "2019-03-14",
      "phone": "+5511999999999",
      "trade_name": "Acme"
    },
    "representative": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "document": "12345678901",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888",
      "verification": {
        "document": {
          "back": "file_trEYw8f2zNM2A9W4",
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cnh"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    },
    "statement_descriptor": "ACME"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile": {
      "annual_revenue": {
        "amount": 6000000,
        "currency": "brl"
      },
      "url": "https://meusite.com"
    },
    "individual": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888",
      "verification": {
        "document": {
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cnh"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    },
    "statement_descriptor": "MARIA SOUZA"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_account": {
      "account_number": "1234567",
      "bank_code": "341",
      "routing_number": "0001",
      "type": "checking"
    },
    "terms_acceptance": {
      "accepted_at": "2026-07-23T13:58:12Z",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0"
    }
  }'

{
  "id": "org_bRLZQqUe7DrQxY4s",
  "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": "#FF6B00",
    "border_style": "rounded",
    "brand_color": "#1B1B1B",
    "font_family": null,
    "theme": "light"
  },
  "business_profile": null,
  "company": null,
  "created_at": "2026-05-16T14:09:27Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "financeiro@meusite.com",
  "individual": null,
  "livemode": true,
  "metadata": {},
  "name": "Acme Brasil Ltda",
  "payout_account": null,
  "platform": "plat_SBCP4YK2WXHeBSnG",
  "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:35:00Z",
  "website": "https://meusite.com"
}

{
  "error": {
    "code": "invalid_request",
    "message": "representative.document must be a valid CPF (11 digits)",
    "param": "representative.document",
    "type": "invalid_request_error"
  }
}

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

{
  "error": {
    "code": "resource_missing",
    "message": "Organization not found",
    "type": "invalid_request_error"
  }
}

Atualiza campos públicos da organização e os blocos do cadastro financeiro (company, representative/individual com verification, business_profile, payout_account, terms_acceptance e statement_descriptor). A operação tem semântica de merge: apenas os campos enviados são modificados. Este é o endpoint de escrita da ativação por API: preencha os blocos, releia requirements.missing e, quando ele zerar, chame POST /v1/organizations/{id}/submit. O fluxo ponta a ponta está em Ativação por API. platform, activation_status, activation_status_updated_at, activation_submitted_at, requirements, created_at e updated_at são somente leitura: enviá-los retorna 400. document e document_type podem ser alterados apenas enquanto a organização ainda não tem identidade financeira viva: a ativação precisa estar em not_submitted ou disabled e a organização não pode ter nenhuma atividade de pagamento. Depois da primeira ativação ou movimentação, o documento identifica o histórico financeiro e se torna permanente. Veja o modelo completo em Reenviar KYC de uma organização.

Autenticação

Credencial	Acesso
API key da plataforma (`platform_admin`)	Organizações conectadas ativas da plataforma. Também permite atualizar `metadata` da relação.

A organização vem do {id} da URL. Com chave de plataforma, não envie o header Organization: a API valida se a organização do caminho tem uma conexão ativa com a plataforma da chave.

O ID da URL sempre prevalece. Um header Organization diferente não troca o alvo da atualização. Para evitar atualizar a conta errada, não envie esse header nesta rota.

Parâmetros de caminho

string

required

ID da organização.

Attributes

string

URL de file da Chargefy (https://storage.chargefy.io/file_...) com purpose organization_avatar, criada via POST /v1/files e pertencente à própria organização. URLs externas são rejeitadas com 400. Use null para limpar.

object

Conta para saques declarada para receber os repasses. Bloco atômico: account_number, bank_code, routing_number e type são obrigatórios juntos. bank_name é opcional. Use null para limpar a declaração.

Show Campos de payout_account

string

required

Número completo da conta. O valor é usado apenas no cadastro financeiro; as respostas públicas retornam somente os quatro últimos dígitos.

string

required

Código bancário de três dígitos.

string

Nome do banco. Quando omitido, a Chargefy tenta preenchê-lo a partir da infraestrutura financeira durante o envio do cadastro.

string

required

Agência ou identificador de roteamento.

string

required

Tipo da conta.

Valor	Descrição
`checking`	Conta corrente.
`savings`	Conta poupança.

O titular nunca é enviado: holder_name e document são derivados da identidade da organização e retornam 400 se aparecerem no corpo.Na escrita, payout_account declara a conta que será usada no envio do cadastro. Na leitura, o mesmo campo mostra a conta ativa do cadastro financeiro (objeto payout_account com pa_* e últimos 4 dígitos) — os dois lados só coincidem depois da aprovação. A conta é propriedade do documento fiscal: o novo valor passa a valer para as cobranças daquele CPF/CNPJ.

string

Informação adicional de cobrança. Use null para limpar.

object

Endereço de cobrança. Use null para limpar.

string

Nome usado em cobranças. Use null para limpar.

object

Identidade visual usada por invoices e pelo portal do cliente. Merge por campo: cada campo enviado é atualizado, os demais permanecem. Use null em um campo para limpá-lo. O checkout hospedado é configurado no Checkout Builder.

Show Campos de branding_settings

string

Estilo de borda de botões e campos.

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

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.

Estes defaults valem para todas as checkout sessions da organização; cada sessão pode sobrescrever campos pontualmente. A cópia do botão (submit_type) não mora aqui — é definida por sessão.

object

Perfil de negócio declarado. Merge por campo: enviar só url mantém o annual_revenue guardado.

Show Campos de business_profile

object

Faturamento anual declarado: amount (inteiro positivo, em centavos) e currency (sempre "brl"). Use null para limpar.

string

Site ou página do negócio, http:// ou https://. Use null para limpar.

mcc é somente leitura: a categoria do negócio é resolvida pela Chargefy a partir do registro público do CNPJ. Enviá-lo retorna 400.

object

Dados cadastrais da empresa. Aceito apenas em organizações CNPJ; em organizações CPF retorna 400. Merge por campo.

Show Campos de company

object

Endereço da empresa. Atômico: quando enviado, é validado inteiro e substitui o anterior. Campos: line1, number, neighborhood, city, state (2 letras) e postal_code (8 dígitos) obrigatórios; line2 opcional.

string

E-mail da empresa.

string

Razão social.

string

Data de abertura, YYYY-MM-DD.

string

Telefone com DDD. Guardado normalizado (10 ou 11 dígitos).

string

Nome fantasia.

Em organizações CNPJ, estes campos são preenchidos automaticamente a partir do registro público do CNPJ logo após a criação; o que você grava sempre vence.

string

Novo CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação. O documento é a identidade fiscal declarada da organização: ele define qual perfil financeiro a próxima activation session vai criar (pessoa física para CPF, pessoa jurídica para CNPJ).Só pode ser alterado enquanto activation_status é not_submitted ou disabled e a organização não tem atividade de pagamento. A troca desativa o perfil financeiro reprovado anterior (se houver) e reinicia qualquer activation session aberta — chame POST /v1/activation-sessions novamente após a troca.

string

Tipo do documento. Opcional: quando omitido, é derivado do document. Quando enviado, precisa ser coerente com o número informado. Não pode ser enviado sem document.

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

string

E-mail principal. Use null para limpar.

object

A pessoa física titular da organização. Aceito apenas em organizações CPF; em organizações CNPJ retorna 400. Mesmos campos de representative, com uma exceção: individual.document não é aceito — o documento da organização já é o CPF dessa pessoa.

object

Substitui a metadata da relação plataforma↔organização conectada. Disponível apenas com API key de plataforma.

Use metadata para guardar referências do seu sistema na relação entre a plataforma autenticada e a organização conectada.

string

Nome público da organização. Não aceita string vazia.

object

O representante legal da empresa. Aceito apenas em organizações CNPJ; em organizações CPF retorna 400. Merge por campo.

Show Campos de representative

object

Endereço residencial. Atômico, mesmas regras de company.address.

object

Arquivos de verificação da pessoa, referenciados por ID de arquivo (file_*). Faça o upload antes com POST /v1/files usando purpose=kyc_document.

Show Campos de verification

object

Arquivos do documento de identidade. Atômico: substitui frente, verso e tipo de uma vez. front (file_*) e type (cnh, rg, cref, cin ou passport) são obrigatórios. back é obrigatório para rg, opcional para cnh, cref e cin e não é aceito para passport. cnh ou cin sem back representam o documento digital: front precisa ser o PDF oficial do app do governo (CNH Digital ou gov.br) — para fotos do documento físico, envie front e back. A selfie aceita somente imagem. No upload do file_*, imagens podem ter até 20 MB e são normalizadas automaticamente; PDFs podem ter até 5 MB.

string

ID (file_*) da selfie. Enviar um novo ID substitui a selfie atual; omitir o campo preserva o arquivo já associado. Em uma correção, reenvie a selfie somente quando requirements.missing contiver o caminho representative.verification.selfie.

Cada arquivo só pode ocupar um espaço: o mesmo file_* (ou o mesmo conteúdo) em dois campos retorna 400. As fotos nunca voltam na resposta — o progresso aparece em requirements.

array

Substitui a lista inteira de redes sociais. Use [] para limpar.

string

Nome exibido na fatura do comprador. Normalizado para maiúsculas, sem acentos, apenas letras, números e espaços; precisa ficar entre 5 e 22 caracteres depois da normalização. Use null para limpar.É propriedade do documento fiscal: o novo valor passa a valer para as cobranças daquele CPF/CNPJ. Depois do cadastro aprovado, a leitura devolve o valor em vigor no cadastro financeiro.

object

Registro do aceite dos termos de serviço coletado por você. Bloco atômico; use null para limpar.

Show Campos de terms_acceptance

string

Site público. Use null para limpar.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "branding_settings": {
      "accent_color": "#FF6B00",
      "border_style": "rounded",
      "brand_color": "#1B1B1B",
      "theme": "light"
    },
    "email": "financeiro@meusite.com",
    "metadata": {},
    "name": "Acme Brasil Ltda"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile": {
      "annual_revenue": {
        "amount": 120000000,
        "currency": "brl"
      },
      "url": "https://meusite.com"
    },
    "company": {
      "address": {
        "city": "São Paulo",
        "line1": "Avenida Paulista",
        "line2": "Conjunto 101",
        "neighborhood": "Bela Vista",
        "number": "1000",
        "postal_code": "01310100",
        "state": "SP"
      },
      "email": "financeiro@meusite.com",
      "name": "ACME COMERCIO LTDA",
      "opening_date": "2019-03-14",
      "phone": "+5511999999999",
      "trade_name": "Acme"
    },
    "representative": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "document": "12345678901",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888",
      "verification": {
        "document": {
          "back": "file_trEYw8f2zNM2A9W4",
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cnh"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    },
    "statement_descriptor": "ACME"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile": {
      "annual_revenue": {
        "amount": 6000000,
        "currency": "brl"
      },
      "url": "https://meusite.com"
    },
    "individual": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888",
      "verification": {
        "document": {
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cnh"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    },
    "statement_descriptor": "MARIA SOUZA"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_account": {
      "account_number": "1234567",
      "bank_code": "341",
      "routing_number": "0001",
      "type": "checking"
    },
    "terms_acceptance": {
      "accepted_at": "2026-07-23T13:58:12Z",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0"
    }
  }'

Exemplos completos de documento de identidade

Os exemplos abaixo usam uma organização CNPJ, por isso o bloco é representative.verification. Em uma organização CPF, envie exatamente o mesmo conteúdo em individual.verification.

(a) CNH digital

Use o PDF oficial exportado do app CNH Digital em front e omita back.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cnh"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    }
  }'

(b) CNH física, frente e verso

Use dois arquivos quando enviar fotos da CNH física.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_trEYw8f2zNM2A9W4",
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cnh"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    }
  }'

(c) RG, frente e verso

O RG sempre exige os dois lados em arquivos separados.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_trEYw8f2zNM2A9W4",
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "rg"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    }
  }'

(d) CREF completo

Use um único arquivo da carteira aberta, em imagem ou PDF, em front.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cref"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    }
  }'

(e) CREF, frente e verso

Use dois arquivos quando a carteira não estiver aberta em um único arquivo.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_trEYw8f2zNM2A9W4",
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cref"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    }
  }'

(f) CIN digital

Use o PDF oficial exportado do app gov.br em front e omita back.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cin"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    }
  }'

(g) CIN física, frente e verso

Use dois arquivos quando enviar fotos da CIN física.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_trEYw8f2zNM2A9W4",
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cin"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    }
  }'

(h) Passaporte

Use somente a página de identificação em front; back não é aceito.

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "passport"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    }
  }'

Resposta

200 OK com o objeto organization completo e já atualizado. A resposta direta não inclui diff.

{
  "id": "org_bRLZQqUe7DrQxY4s",
  "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": "#FF6B00",
    "border_style": "rounded",
    "brand_color": "#1B1B1B",
    "font_family": null,
    "theme": "light"
  },
  "business_profile": null,
  "company": null,
  "created_at": "2026-05-16T14:09:27Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "financeiro@meusite.com",
  "individual": null,
  "livemode": true,
  "metadata": {},
  "name": "Acme Brasil Ltda",
  "payout_account": null,
  "platform": "plat_SBCP4YK2WXHeBSnG",
  "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:35:00Z",
  "website": "https://meusite.com"
}

{
  "error": {
    "code": "invalid_request",
    "message": "representative.document must be a valid CPF (11 digits)",
    "param": "representative.document",
    "type": "invalid_request_error"
  }
}

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

{
  "error": {
    "code": "resource_missing",
    "message": "Organization not found",
    "type": "invalid_request_error"
  }
}

Erros de acesso

HTTP	`code`	Quando acontece	O que fazer
`401`	`authentication_failed`	Credencial ausente, inválida, revogada ou expirada.	Confira a API key e o ambiente.
`403`	`permission_denied`	A sessão do Dashboard não tem permissão para administrar a organização.	Use um usuário com a capability necessária.
`404`	`resource_missing`	Organização inexistente, removida, fora do escopo da chave ou sem conexão ativa com a plataforma.	Confira o `org_*` e a conexão. O header `Organization` não corrige esse erro.

Erros dos blocos de cadastro

Toda recusa de validação é 400 com type: "invalid_request_error", code: "invalid_request" e param no caminho exato do campo. As mensagens abaixo são as que a API devolve, literalmente.

Bloco fora do tipo de documento

`param`	`message`
`company`	`company is only valid for organizations with a CNPJ document`
`representative`	`representative is only valid for organizations with a CNPJ document`
`individual`	`individual is only valid for organizations with a CPF document`

`company`

`param`	`message`
`company`	`company must be an object`
`company.address`	`company.address must be an object or null`
`company.address.line1`	`company.address.line1 is required`
`company.address.number`	`company.address.number is required`
`company.address.neighborhood`	`company.address.neighborhood is required`
`company.address.city`	`company.address.city is required`
`company.address.state`	`company.address.state must be a 2-letter state code (e.g. SP)`
`company.address.postal_code`	`company.address.postal_code must have 8 digits`
`company.email`	`company.email must be a valid email address`
`company.opening_date`	`company.opening_date must be an ISO 8601 date (YYYY-MM-DD)`
`company.opening_date`	`company.opening_date must be a valid calendar date`
`company.phone`	`company.phone must be a Brazilian phone number with area code (10 or 11 digits)`

`representative` e `individual`

O prefixo do param acompanha o bloco enviado (representative em organizações CNPJ, individual em CPF).

`param`	`message`
`representative`	`representative must be an object`
`individual.document`	`individual.document is not accepted: the organization document is the person's CPF`
`representative.document`	`representative.document must be a valid CPF (11 digits)`
`representative.first_name`	`representative.first_name must not contain numbers`
`representative.first_name`	`representative.first_name must be the person's civil name, not the company name`
`representative.birthdate`	`representative.birthdate must be an ISO 8601 date (YYYY-MM-DD)`
`representative.email`	`representative.email must be a valid email address`
`representative.phone`	`representative.phone must be a Brazilian phone number with area code (10 or 11 digits)`
`representative.address.state`	`representative.address.state must be a 2-letter state code (e.g. SP)`

`verification`

`param`	`message`
`representative.verification`	`representative.verification must be an object`
`representative.verification.document`	`representative.verification.document must be an object`
`representative.verification.document.front`	`representative.verification.document.front is required`
`representative.verification.document.front`	`representative.verification.document.front must be a file id (file_...)`
`representative.verification.document.type`	`representative.verification.document.type must be one of: cnh, rg, cref, cin, passport`
`representative.verification.document.back`	`representative.verification.document.back is required: rg verification needs the front and the back files`
`representative.verification.document.back`	`representative.verification.document.back is not accepted: passport verification uses a single complete file in document.front`
`representative.verification.document.front`	`representative.verification.document.front must be the official digital CNH PDF (CNH Digital app export). To send photos of the physical CNH, declare document.front and document.back`
`representative.verification.document.front`	`representative.verification.document.front must be the official digital CIN PDF (gov.br app export)`
`representative.verification.document.front`	`representative.verification.document.front exceeds the 5 MB limit for verification files`
`representative.verification.selfie`	`representative.verification.selfie must be a file id (file_...)`
`representative.verification.selfie`	`representative.verification.selfie must be one of: image/jpeg, image/png, image/webp, image/bmp, image/heic, image/heif`

Duas recusas do bloco de verificação não trazem param:

`code`	`message`
`resource_missing`	`file file_p3M9s5WHC9Jvrn3c not found for this organization`
`invalid_request`	`the same file cannot be used for more than one verification slot`

Arquivo não encontrado e arquivo de outra organização compartilham a mesma mensagem — a existência de arquivos de terceiros nunca é revelada.

`business_profile`

`param`	`message`
`business_profile`	`business_profile must be an object`
`business_profile.mcc`	`business_profile.mcc is read-only`
`business_profile.annual_revenue`	`business_profile.annual_revenue must be an object with amount and currency`
`business_profile.annual_revenue.amount`	`business_profile.annual_revenue.amount must be a positive integer (amount in cents)`
`business_profile.annual_revenue.currency`	`business_profile.annual_revenue.currency must be 'brl'`
`business_profile.url`	`business_profile.url must be a valid URL`
`business_profile.url`	`business_profile.url must be an http(s) URL`

`payout_account`

`param`	`message`
`payout_account`	`payout_account must be an object or null`
`payout_account.holder_name`	`payout_account.holder_name is not accepted: the holder is derived from the organization identity`
`payout_account.document`	`payout_account.document is not accepted: the holder is derived from the organization identity`
`payout_account.bank_code`	`payout_account.bank_code must be the 3-digit bank code`
`payout_account.bank_name`	`payout_account.bank_name must be a string or null`
`payout_account.routing_number`	`payout_account.routing_number must contain the branch number (digits only)`
`payout_account.account_number`	`payout_account.account_number must contain the account number (digits only)`
`payout_account.type`	`payout_account.type must be one of: checking, savings`

`terms_acceptance` e `statement_descriptor`

`param`	`message`
`terms_acceptance`	`terms_acceptance must be an object or null`
`terms_acceptance.accepted_at`	`terms_acceptance.accepted_at is required`
`terms_acceptance.accepted_at`	`terms_acceptance.accepted_at must be an ISO 8601 timestamp`
`terms_acceptance.accepted_at`	`terms_acceptance.accepted_at cannot be in the future`
`terms_acceptance.ip`	`terms_acceptance.ip is required`
`terms_acceptance.ip`	`terms_acceptance.ip must be a valid IP address`
`terms_acceptance.user_agent`	`terms_acceptance.user_agent must be a string`
`statement_descriptor`	`statement_descriptor must be a string or null`
`statement_descriptor`	`statement_descriptor must be 5 to 22 characters (letters, numbers and spaces)`

Erros de troca de documento

HTTP	`code`	Situação
`400`	`invalid_request`	`document` inválido, ou `document_type` incoerente com o número enviado.
`409`	`organization_already_active`	A organização já está ativa. O documento identifica o histórico financeiro e não pode mais ser trocado.
`409`	`organization_activation_in_review`	Existe uma análise de ativação em andamento. Aguarde o resultado (`organization.updated`) antes de trocar.
`409`	`organization_has_payment_activity`	A organização já tem atividade de pagamento; o documento é permanente.
`409`	`document_already_in_use`	Outra organização conectada da mesma plataforma já usa esse documento. Use a organização existente em vez de trocar.

Webhook

Quando a chamada altera campos visíveis para uma plataforma conectada, a Chargefy emite organization.updated para os endpoints da organização da plataforma. data.object contém o snapshot completo atualizado. data.previous_attributes contém apenas os campos alterados e seus valores anteriores — quando requirements muda, o diff traz o objeto anterior completo. Em uma troca de documento após reprovação, a vinculação com o perfil financeiro reprovado é desativada: activation_status volta para not_submitted, requirements recomeça pelo missing do novo documento e statement_descriptor volta para null.

No webhook, o campo top-level organization identifica a organização conectada que mudou. Para reler o estado, use esse valor em GET /v1/organizations/{id}, sem header Organization.

{
  "id": "evt_eCUnL8bUb7GccwtD",
  "object": "event",
  "created_at": "2026-05-16T14:35:00Z",
  "data": {
    "object": {
      "id": "org_bRLZQqUe7DrQxY4s",
      "object": "organization",
      "activation_status": "not_submitted",
      "activation_status_updated_at": "2026-05-16T14:35:00Z",
      "activation_submitted_at": "2026-05-16T14:12:00Z",
      "avatar_url": null,
      "billing_additional_info": null,
      "billing_address": null,
      "billing_name": null,
      "branding_settings": {
        "accent_color": "#FF6B00",
        "border_style": "rounded",
        "brand_color": "#1B1B1B",
        "font_family": null,
        "theme": "light"
      },
      "business_profile": null,
      "company": null,
      "created_at": "2026-05-16T14:09:27Z",
      "dashboard_settings": {
        "timezone": "America/Sao_Paulo"
      },
      "document": "12345678901",
      "document_type": "cpf",
      "email": "financeiro@meusite.com",
      "individual": null,
      "livemode": true,
      "metadata": {},
      "name": "Acme Brasil Ltda",
      "payout_account": null,
      "platform": "plat_SBCP4YK2WXHeBSnG",
      "representative": null,
      "requirements": {
        "disabled_reason": null,
        "errors": [],
        "missing": [
          "payout_account",
          "business_profile.annual_revenue",
          "individual.address",
          "individual.birthdate",
          "individual.document",
          "individual.email",
          "individual.first_name",
          "individual.last_name",
          "individual.phone",
          "individual.verification.document",
          "individual.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:35:00Z",
      "website": "https://meusite.com"
    },
    "previous_attributes": {
      "activation_status": "disabled",
      "document": "12345678000190",
      "document_type": "cnpj",
      "requirements": {
        "disabled_reason": null,
        "errors": [
          {
            "code": "registration_data_inconsistent",
            "message": "The registration data provided does not match official records.",
            "requirement": "company",
            "resolution": "Ask the account holder to correct the indicated registration data — name, date of birth, address and taxpayer id — then start a new activation attempt."
          }
        ],
        "missing": [
          "company"
        ],
        "pending_verification": []
      },
      "statement_descriptor": "ACME BRASIL LTDA"
    }
  },
  "livemode": true,
  "organization": "org_bRLZQqUe7DrQxY4s",
  "request": {
    "id": "req_LVBRSB2APGMgfa6c"
  },
  "type": "organization.updated"
}

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "branding_settings": {
      "accent_color": "#FF6B00",
      "border_style": "rounded",
      "brand_color": "#1B1B1B",
      "theme": "light"
    },
    "email": "financeiro@meusite.com",
    "metadata": {},
    "name": "Acme Brasil Ltda"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile": {
      "annual_revenue": {
        "amount": 120000000,
        "currency": "brl"
      },
      "url": "https://meusite.com"
    },
    "company": {
      "address": {
        "city": "São Paulo",
        "line1": "Avenida Paulista",
        "line2": "Conjunto 101",
        "neighborhood": "Bela Vista",
        "number": "1000",
        "postal_code": "01310100",
        "state": "SP"
      },
      "email": "financeiro@meusite.com",
      "name": "ACME COMERCIO LTDA",
      "opening_date": "2019-03-14",
      "phone": "+5511999999999",
      "trade_name": "Acme"
    },
    "representative": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "document": "12345678901",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888",
      "verification": {
        "document": {
          "back": "file_trEYw8f2zNM2A9W4",
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cnh"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    },
    "statement_descriptor": "ACME"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile": {
      "annual_revenue": {
        "amount": 6000000,
        "currency": "brl"
      },
      "url": "https://meusite.com"
    },
    "individual": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888",
      "verification": {
        "document": {
          "front": "file_p3M9s5WHC9Jvrn3c",
          "type": "cnh"
        },
        "selfie": "file_fD4f67g8FH918uAW"
      }
    },
    "statement_descriptor": "MARIA SOUZA"
  }'

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_account": {
      "account_number": "1234567",
      "bank_code": "341",
      "routing_number": "0001",
      "type": "checking"
    },
    "terms_acceptance": {
      "accepted_at": "2026-07-23T13:58:12Z",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0"
    }
  }'

{
  "id": "org_bRLZQqUe7DrQxY4s",
  "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": "#FF6B00",
    "border_style": "rounded",
    "brand_color": "#1B1B1B",
    "font_family": null,
    "theme": "light"
  },
  "business_profile": null,
  "company": null,
  "created_at": "2026-05-16T14:09:27Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": "financeiro@meusite.com",
  "individual": null,
  "livemode": true,
  "metadata": {},
  "name": "Acme Brasil Ltda",
  "payout_account": null,
  "platform": "plat_SBCP4YK2WXHeBSnG",
  "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:35:00Z",
  "website": "https://meusite.com"
}

{
  "error": {
    "code": "invalid_request",
    "message": "representative.document must be a valid CPF (11 digits)",
    "param": "representative.document",
    "type": "invalid_request_error"
  }
}

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

{
  "error": {
    "code": "resource_missing",
    "message": "Organization not found",
    "type": "invalid_request_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Atualizar uma organização

Autenticação

Parâmetros de caminho

Attributes

Exemplos completos de documento de identidade

(a) CNH digital

(b) CNH física, frente e verso

(c) RG, frente e verso

(d) CREF completo

(e) CREF, frente e verso

(f) CIN digital

(g) CIN física, frente e verso

(h) Passaporte

Resposta

Erros de acesso

Erros dos blocos de cadastro

Bloco fora do tipo de documento

`company`

`representative` e `individual`

`verification`

`business_profile`

`payout_account`

`terms_acceptance` e `statement_descriptor`

Erros de troca de documento

Webhook

​Autenticação

​Parâmetros de caminho

​Attributes

​Exemplos completos de documento de identidade

​(a) CNH digital

​(b) CNH física, frente e verso

​(c) RG, frente e verso

​(d) CREF completo

​(e) CREF, frente e verso

​(f) CIN digital

​(g) CIN física, frente e verso

​(h) Passaporte

​Resposta

​Erros de acesso

​Erros dos blocos de cadastro

​Bloco fora do tipo de documento

​company

​representative e individual

​verification

​business_profile

​payout_account

​terms_acceptance e statement_descriptor

​Erros de troca de documento

​Webhook

Autenticação

Parâmetros de caminho

Attributes

Exemplos completos de documento de identidade

(a) CNH digital

(b) CNH física, frente e verso

(c) RG, frente e verso

(d) CREF completo

(e) CREF, frente e verso

(f) CIN digital

(g) CIN física, frente e verso

(h) Passaporte

Resposta

Erros de acesso

Erros dos blocos de cadastro

Bloco fora do tipo de documento

`company`

`representative` e `individual`

`verification`

`business_profile`

`payout_account`

`terms_acceptance` e `statement_descriptor`

Erros de troca de documento

Webhook