> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plataformas: organizações conectadas

> Crie, faça a ativação e opere organizações conectadas usando API key de plataforma e o header Organization.

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.

<Note>
  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`.
</Note>

| 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`.                                                      |

<Warning>
  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.
</Warning>

## Fluxo recomendado

1. Crie a organização conectada para o CPF/CNPJ da conta.

2. Guarde o `id` retornado no seu sistema.

3. 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:
     [Ativação hospedada](/platforms/activate-with-hosted-session).
   * **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:
     [Ativação por API](/platforms/activate-by-api).

   Os dois escrevem no mesmo cadastro e o resultado chega pelo mesmo
   `organization.updated`.

4. Acompanhe `organization.created`, `organization.review.required`,
   `organization.review.submitted` e `organization.updated` por webhook.

5. 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

```bash theme={"theme":"css-variables"}
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:

```json theme={"theme":"css-variables"}
{
  "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": 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": null,
  "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,
  "terms_acceptance": 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.

<Tip>
  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.
</Tip>

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}`](/api-reference/organizations/update) — ú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](/platforms/resubmit-organization-verification).

Veja o contrato completo em [Criar organização](/api-reference/organizations/create).

## 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.

```bash theme={"theme":"css-variables"}
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](/api-reference/activation-sessions/create).

## 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.

<Warning>
  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`.
</Warning>

Exemplo criando uma sessão de checkout:

```bash theme={"theme":"css-variables"}
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:

```bash theme={"theme":"css-variables"}
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:

```bash theme={"theme":"css-variables"}
curl -X GET "https://api.chargefy.io/v1/organizations/org_DYJKZasdWN1zt4Jd" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}"
```

<Note>
  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.
</Note>

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`](/api-reference/payout-accounts/object) 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 ou status de ativação financeira mudaram.
* 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.

<Tip>
  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.
</Tip>

## 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` |