Skip to main content
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.

​
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, crie um onboarding session para o organization_id e envie o responsável pela conta para a url retornada.
  4. Acompanhe organization.created, onboarding.session.submitted, organization.review.required, organization.review.submitted e organization.updated por webhook.
  5. Para criar recursos para essa organização, 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 resumida: 
{
  "id": "org_123",
  "object": "organization",
  "activation_status": "activation_pending",
  "document": "12345678000190",
  "document_type": "cnpj",
  "metadata": {},
  "name": "Acme Ltda",
  "platform_id": "plat_123"
}
Chamadas repetidas com o mesmo CPF/CNPJ dentro da mesma plataforma retornam a mesma organização. Guarde o id retornado; ele é o valor usado no header Organization. O document é a identidade fiscal declarada da organização: ele define se o onboarding financeiro 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. Veja o contrato completo em Criar organização.

​
Criar o onboarding session

Quando a organização precisar completar o cadastro financeiro, crie uma onboarding 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/onboarding-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "return_url": "https://meusite.com/onboarding/return"
  }'
A URL expira em 60 segundos. Para renovar, chame POST /v1/onboarding-sessions de novo com o mesmo organization_id. Veja o contrato completo em Criar onboarding 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. 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_123" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_123",
        "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_123" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_123",
        "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 bancária

Para exibir a conta bancária cadastrada do host no admin da plataforma, consulte a organização conectada: 
curl -X GET "https://api.chargefy.io/v1/organizations/org_123" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}"
A conta ativa aparece em bank_account. Esse objeto inclui o ba_*, banco, agência/roteamento, titular, tipo da conta, is_active, is_verified e os quatro últimos dígitos. O número completo da conta nunca é retornado. Quando a conta conectada muda, o webhook organization.updated também envia o snapshot atual em data.object.bank_account. Para listar ou consultar contas diretamente por ba_*, use os endpoints de bank_accounts com o header Organization.

​
Webhooks

Configure um endpoint para receber estes eventos:
  • organization.created: a organização conectada foi criada e vinculada à plataforma.
  • onboarding.session.submitted: a organização conectada concluiu o preenchimento do cadastro inicial.
  • 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.

​
Erros comuns

SituaçãoResposta
API key não é de plataforma403
Header Organization ausente em chamada que exige atuação de plataforma403
Organization aponta para organização sem vínculo ativo com a plataforma403
Organização ou onboarding session criado antes do setup da plataforma409
URL do onboarding session expiradaChame POST /v1/onboarding-sessions novamente com o mesmo organization_id