Skip to main content
Use o modelo de plataforma quando seu produto permite que outras empresas ou pessoas operem pagamentos. Cada vendedor, loja ou unidade se torna uma organização conectada com cadastro, ativação e recursos próprios. Sua plataforma mantém uma integração central. O org_* identifica cada conta conectada e define onde os dados e pagamentos pertencem.
Na API pública, uma conta conectada é um objeto organization (org_*). Não existe um objeto separado chamado subconta. Use sempre “organização conectada” na interface e na integração.

​
Quando este modelo é adequado

Se toda a operação pertence à mesma empresa e usa o mesmo cadastro financeiro, uma única organização costuma ser suficiente.

​
Como os recursos se organizam

Recursos de organizações diferentes não são agrupados no mesmo contexto. O ID da organização (org_*) deve ser persistido junto ao identificador do vendedor ou da conta no seu sistema.
O recurso /v1/organizations é exclusivo de Platforms. Autentique com a API key de plataforma e use a coleção ou o ID da URL para criar, listar, consultar ou atualizar uma organização conectada. Para operar customers, produtos, checkouts e pagamentos dessa conta, envie o mesmo org_* no header Organization.

​
Fluxo da organização conectada

1

Crie a organização

Envie nome e CPF/CNPJ para POST /v1/organizations. Guarde o org_* retornado.
2

Conclua a ativação

Use uma Activation Session hospedada ou envie o cadastro diretamente pela API. Os dois caminhos atualizam a mesma organização.
3

Acompanhe o status

Leia activation_status e requirements e processe os eventos organization.*.
4

Opere no contexto correto

Envie a API key de plataforma e Organization: org_AinWSrAyKnG9x73A para criar customers, checkouts, pagamentos e outros recursos daquela organização.
Não confunda conexão ativa com ativação financeira. A conexão permite que a plataforma acesse a conta; activation_status: "active" informa que o perfil financeiro pode processar pagamentos. Uma conta em cadastro ou reprovação continua sendo a mesma organização conectada. Nos endpoints de recursos da conta, header ausente ou conexão inativa retorna 403.

​
Escolha o modelo de ativação

Os caminhos podem ser usados em momentos diferentes sobre a mesma organização. O resultado chega pelo objeto organization e pelo evento organization.updated.
Guarde um único org_* por vendedor. Use-o na URL dos endpoints de organizações, no header dos recursos da conta e para correlacionar o campo top-level organization recebido nos webhooks.

​
Eventos da plataforma

Crie um endpoint com events_from: "platform" para receber eventos originados pelas organizações conectadas. O campo top-level organization identifica a conta que gerou cada evento. O mesmo endpoint recebe os eventos fee.plan.* dos planos de taxas da sua plataforma. Neles, organization é a organização da própria plataforma. Os demais eventos da organização da plataforma não chegam a esse endpoint. Se você precisa deles, crie outro endpoint com events_from: "organization".

​
Decisões antes de implementar

  • qual entidade do seu produto corresponde a uma organização conectada;
  • quem coleta e corrige os dados de ativação;
  • quais telas e ações a plataforma expõe para cada conta;
  • com qual marca e em qual domínio as páginas hospedadas das vendas criadas pela plataforma aparecem — os da organização conectada ou os da plataforma (veja Marca e domínio próprio);
  • quanto cada organização conectada paga por venda e se ela segue o plano padrão ou um plano fixado (veja Planos de taxas);
  • quais eventos atualizam seu estado local;
  • como o suporte identifica a organização responsável por cada operação.
O MCP da Chargefy lista e consulta organizações conectadas a partir do seu assistente, e o plugin do Claude Code traz as skills de integração e o revisor de código. Cada conexão vale para uma organização e é autorizada por ambiente.

​
Próximos passos

Operar organizações conectadas

Implemente criação, ativação, header Organization e webhooks.

Ativar organização por sessão hospedada

Redirecione o responsável para uma Activation Session.

Ativar organização por API

Colete e envie o cadastro dentro do seu produto.

Requisitos de ativação

Trate pendências, reprovações e novas tentativas.

Marca e domínio próprio

Escolha quem apresenta as vendas das organizações conectadas: a marca e o domínio da plataforma ou os de cada organização.

Planos de taxas

Defina quanto cada organização conectada paga por venda e escolha o plano padrão.