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.Fluxo recomendado
- Crie a organização conectada para o CPF/CNPJ da conta.
-
Guarde o
idretornado no seu sistema. -
Quando precisar de cadastro financeiro, escolha um dos dois caminhos:
- Hospedado — crie um activation session para o
organizatione envie o responsável pela conta para aurlretornada. É 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 comPOST /v1/organizations/{id}/submit, sem redirecionar ninguém. Guia: Ativar organização por API.
organization.updated. - Hospedado — crie um activation session para o
-
Acompanhe
organization.created,organization.review.required,organization.review.submittedeorganization.updatedpor webhook. -
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
requirements.missing já mostra o que o cadastro financeiro ainda
precisa:
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, e a tabela de juros vem desse plano. Semfee_plan, ela recebe o plano padrão
atual; com o ID de um plano, usa esse plano. Trocar o padrão depois não muda as
organizações que já existem. 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 o ID do plano atribuído:
fee_plan em
POST /v1/organizations/{id}: o ID de
outro plano, ou "default" para fixar o padrão atual. 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 oid da organização. A resposta emite uma URL fresca
para o fluxo hospedado.
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 daorganization, envie esse valor no header
Organization em endpoints que aceitam atuação de plataforma.
Exemplo criando uma sessão de checkout:
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: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.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. A própria API key de plataforma cadastra o endpoint emPOST /v1/webhook-endpoints, com
events_from: "platform" e o header Organization apontando para a
organização da sua plataforma:
secret, que também volta em toda consulta do endpoint. Com o header de uma organização
filha, a mesma chave cadastra endpoints que recebem só os eventos daquela
organização.
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.- Eventos do recurso criado pela organização conectada, como
payment.intent.succeededecheckout.session.completed.
data.object. Use o campo top-level
organization do evento para identificar a organização conectada que originou
o evento.
Erros comuns
Conta bloqueada
Quando uma organização conectada está comrequirements.disabled_reason igual
a blocked.account, a plataforma dona pode consultá-la no painel e operar
pela API em modo de leitura. Escritas, inclusive estornos, recebem
403 organization_blocked. A
liberação ou troca de nível chega em
organization.updated.
Se o bloqueio for na conta da própria plataforma, as chaves emitidas por ela
perdem o acesso. As organizações conectadas continuam operando por seus
próprios canais, conforme o status de cada uma.
