Plataformas: organizações conectadas

Uma plataforma usa uma API key de plataforma para criar organizações conectadas e, depois, operar recursos delas pelo header Organization. O identificador público que você guarda é o ID da organization (org_*). Não existe um objeto público separado para o vínculo plataforma↔organização.

O mesmo org_* tem dois usos. Para consultar ou atualizar a própria organização, coloque o ID na URL. Para operar recursos pertencentes a ela, como produtos, customers e pagamentos, envie o ID no header Organization.

O que você quer fazer	Como informar a organização
Criar ou listar organizações	Use `/v1/organizations`; não envie `Organization`.
Consultar, atualizar ou enviar uma organização	Use `/v1/organizations/{id}` ou `/v1/organizations/{id}/submit`; o ID da URL define o alvo.
Operar produtos, customers, checkouts, pagamentos e outros recursos da conta	Envie `Organization: org_*`.
Identificar a conta em um webhook	Leia o campo top-level `organization`.
Escolher o plano de taxas da organização	Envie `fee_plan` ao criar ou atualizar a organização; não envie `Organization`.

Não adicione o header Organization automaticamente a toda chamada de plataforma. Nos endpoints de organizações, a coleção ou o ID da URL é a fonte de verdade.

Fluxo recomendado

Crie a organização conectada para o CPF/CNPJ da conta.
Guarde o id retornado no seu sistema.
Quando precisar de cadastro financeiro, escolha um dos dois caminhos:
- Hospedado — crie um activation session para o organization e envie o responsável pela conta para a url retornada. É o caminho de menor esforço: o formulário, os uploads e as validações são da Chargefy. Guia: Ativar organização por sessão hospedada.
- Por API — colete o cadastro nas suas telas, grave os blocos com POST /v1/organizations/{id} e envie para análise com POST /v1/organizations/{id}/submit, sem redirecionar ninguém. Guia: Ativar organização por API.
Os dois escrevem no mesmo cadastro e o resultado chega pelo mesmo organization.updated.
Acompanhe organization.created, organization.review.required, organization.review.submitted e organization.updated por webhook. Os planos de taxas da plataforma chegam em fee.plan.created e fee.plan.updated.
Para criar recursos pertencentes a essa organização, como produtos, customers e pagamentos, use sua API key de plataforma com Organization: <organization_id>.

Criar a organização conectada

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 — requirements.missing já mostra o que o cadastro financeiro ainda precisa:

{
  "id": "org_DYJKZasdWN1zt4Jd",
  "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",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": null,
  "fee_plan": "default",
  "individual": null,
  "livemode": true,
  "metadata": {},
  "name": "Acme Ltda",
  "payout_account": null,
  "platform": "plat_NcNiqgXszxQKoWbt",
  "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": null
}

Chamadas repetidas com o mesmo CPF/CNPJ dentro da mesma plataforma retornam a mesma organização.

Guarde um único org_* por participante. Esse ID aparece na URL dos endpoints de organizações, no header Organization dos recursos da conta e no campo organization dos webhooks. Se a criação terminar em timeout ou 5xx, repita a chamada com o mesmo documento: a API devolve a mesma organização sem criar duplicata.

O document é a identidade fiscal declarada da organização: ele define se a ativação financeira abre como pessoa física (CPF) ou jurídica (CNPJ). Enquanto a organização não está ativa e não tem atividade de pagamento, o documento pode ser corrigido com POST /v1/organizations/{id} — útil quando um cadastro é reprovado e a conta precisa tentar de novo com outro documento, sem perder produtos e integrações já criados no mesmo org_*. Depois da primeira ativação, o documento é permanente. O fluxo completo está em Reenviar KYC de uma organização. Trocar o documento apaga o cadastro declarado ligado ao anterior: os blocos individual, company, representative, business_profile, o statement_descriptor e a conta para saques voltam a ficar vazios, e os arquivos de verificação são desvinculados (eles continuam em /v1/files e podem ser anexados de novo). É o que impede os documentos de uma pessoa de seguirem colados no CPF/CNPJ de outra. Releia requirements.missing depois da troca para saber o que reenviar. Veja o contrato completo em Criar organização.

Plano de taxas

Toda organização conectada paga as taxas de um plano da sua plataforma. Sem fee_plan, ela segue o plano padrão e acompanha as trocas de padrão; com o ID de um plano, usa esse plano até você trocar. fee_plan só é aceito com chave de produção, porque o plano define o preço das vendas reais; com chave de teste, omita o campo. A resposta traz "default" ou o ID do plano fixado:

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"
  }'

Para trocar depois, envie fee_plan em POST /v1/organizations/{id}: o ID de outro plano, ou "default" para voltar ao padrão. O guia Planos de taxas das organizações filhas explica o plano padrão, a sua margem e quando a taxa vale.

Criar o activation session

Quando a organização precisar completar o cadastro financeiro, crie uma activation session para o id da organização. A resposta emite uma URL fresca para o fluxo hospedado.

curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "org_DYJKZasdWN1zt4Jd",
    "return_url": "https://meusite.com/activation/return"
  }'

A URL expira em 60 segundos. Para renovar, chame POST /v1/activation-sessions de novo com o mesmo organization. Veja o contrato completo em Criar activation session.

Operar na organização conectada

Depois que você tem o ID da organization, envie esse valor no header Organization em endpoints que aceitam atuação de plataforma.

Esta regra vale para recursos pertencentes à conta conectada. Para consultar ou atualizar a própria organização, use GET /v1/organizations/{id} ou POST /v1/organizations/{id} sem o header Organization.

Exemplo criando uma sessão de checkout:

curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_DYJKZasdWN1zt4Jd" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_WuEByDvtyfmyMRJN",
        "quantity": 1
      }
    ],
    "success_url": "https://meusite.com/sucesso",
    "cancel_url": "https://meusite.com/cancelado"
  }'

Exemplo criando um payment link:

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_DYJKZasdWN1zt4Jd" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_WuEByDvtyfmyMRJN",
        "quantity": 1
      }
    ],
    "success_url": "https://meusite.com/obrigado"
  }'

O header Organization é aceito apenas com API key de plataforma. API keys de organização operam somente na própria organização e não podem usar esse header.

Exibir a conta para saques

Para exibir a conta para saques cadastrada do host no admin da plataforma, consulte a organização conectada:

curl -X GET "https://api.chargefy.io/v1/organizations/org_DYJKZasdWN1zt4Jd" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}"

Essa consulta funciona enquanto a conexão entre plataforma e organização estiver ativa, mesmo que activation_status ainda seja not_submitted, in_review ou disabled. O status financeiro só informa se a conta já pode processar pagamentos.

A conta principal aparece em payout_account. Esse objeto inclui o pa_*, banco, agência/roteamento, titular, tipo da conta, os campos legados is_active e is_verified e os quatro últimos dígitos. O número completo da conta nunca é retornado. is_active: true indica apenas qual conta está definida como principal; não confirma que os repasses foram creditados. Oriente a organização a conferir os recebimentos no extrato bancário. Quando a conta conectada muda, o webhook organization.updated também envia o snapshot atual em data.object.payout_account. Para listar ou consultar contas diretamente por pa_*, use os endpoints de payout_accounts com o header Organization.

Webhooks

Configure um endpoint para receber estes eventos:

organization.created: a organização conectada foi criada e vinculada à plataforma.
organization.review.required: há uma atualização cadastral pendente para a organização conectada.
organization.review.submitted: a atualização cadastral hospedada foi enviada para análise.
organization.updated: dados públicos, plano de taxas ou status de ativação financeira mudaram.
fee.plan.created e fee.plan.updated: um plano de taxas da plataforma foi criado ou mudou.
Eventos do recurso criado pela organização conectada, como payment.intent.succeeded e checkout.session.completed.

Em todos eles, o objeto público vem em data.object. Use o campo top-level organization do evento para identificar a organização conectada que originou o evento. Nos eventos fee.plan.*, esse campo é a organização da própria plataforma, porque o plano pertence a ela.

Ao receber um evento de organização, releia o estado atual com GET /v1/organizations/{organization} e a API key de plataforma. Não envie o header Organization nessa consulta.

Erros comuns

Situação	Resposta
API key não é de plataforma	`403`
Header `Organization` ausente em chamada que exige atuação de plataforma	`403`
`Organization` aponta para organização sem vínculo ativo com a plataforma	`403`
Organização ou activation session criado antes do setup da plataforma	`409`
URL do activation session expirada	Chame `POST /v1/activation-sessions` novamente com o mesmo `organization`

Visão geral

Ativação de organizações

Planos de taxas

Marca e domínio próprio

Modelo de negócio

Plataformas: organizações conectadas

Fluxo recomendado

Criar a organização conectada

Plano de taxas

Criar o activation session

Operar na organização conectada

Exibir a conta para saques

Webhooks

Erros comuns

​Fluxo recomendado

​Criar a organização conectada

​Plano de taxas

​Criar o activation session

​Operar na organização conectada

​Exibir a conta para saques

​Webhooks

​Erros comuns

Fluxo recomendado

Criar a organização conectada

Plano de taxas

Criar o activation session

Operar na organização conectada

Exibir a conta para saques

Webhooks

Erros comuns