Plataformas: guia completo de ativação por API

Este guia mostra como ativar financeiramente uma organização conectada sem redirecionar o vendedor: você coleta o cadastro nas suas próprias telas, grava tudo na organização pela API e envia para análise com uma chamada. Ele foi escrito para o time de produto e engenharia de uma plataforma que já tem (ou quer ter) o formulário de cadastro dentro do próprio produto.

Já integra este fluxo? Revise o checklist de mudanças na integração de ativação.

Este guia só se aplica a contas com o produto Chargefy for Platforms habilitado. Nesse produto, uma plataforma opera pagamentos para suas organizações filhas.

Os dois caminhos

Ativar uma organização sempre significa a mesma coisa: entregar dados cadastrais, documento de identidade, selfie e conta para saques para análise. O que muda é quem constrói o formulário.

	Hospedado	Por API
Quem coleta	A Chargefy, em uma página hospedada.	O seu produto, nas suas telas.
O que você constrói	Um botão e um redirect.	Formulário, upload, validações e estados.
Sai do seu produto?	Sim, o vendedor é redirecionado.	Não.
Quem guarda os documentos	A Chargefy.	A Chargefy — os arquivos sobem direto pela API de arquivos.
Como fica pronto	O vendedor conclui e envia na página hospedada.	Você chama `POST /v1/organizations/{id}/submit`.

Use o hospedado quando quiser o menor esforço possível: ele continua existindo, é mantido pela Chargefy e acompanha mudanças regulatórias sozinho. O passo a passo está em Ativação hospedada. Use este caminho quando você já tem cadastro próprio (marketplace com conta de vendedor, ERP, app com fluxo de identidade) e não quer mandar o usuário para fora, ou quando precisa controlar a ordem das telas, a cópia e o momento do envio. Os dois caminhos escrevem no mesmo cadastro da mesma organização, e o resultado chega pelo mesmo evento (organization.updated). Enquanto o cadastro não foi enviado, dá para coletar parte por API e terminar no hospedado: o fluxo hospedado reabre com o que você já gravou.

Pré-requisitos

Plataforma ativa e com o setup concluído.
Uma API key de plataforma com escopo platform_admin (Authorization: Bearer {{PLATFORM_API_KEY}}). O recurso organizations não aceita API keys de organizações padrão.
Um endpoint de webhook registrado — o resultado da análise chega por organization.updated, não por polling.
Um lugar no seu produto para capturar o aceite dos termos (data, hora e IP de quem aceitou).

Nos endpoints /v1/organizations, a coleção ou o ID da URL define qual organização será usada. Não envie o header Organization nessas chamadas. Use esse header apenas em recursos da conta conectada, como o upload de arquivos.

O modelo, em uma frase

A organização é a ficha do cadastro: você escreve os blocos com POST /v1/organizations/{id}, requirements.missing diz exatamente o que ainda falta, e quando missing fica vazio você chama POST /v1/organizations/{id}/submit. Três consequências práticas:

Você nunca precisa adivinhar o que falta: a lista vem pronta, em caminhos pontuados (representative.birthdate, payout_account, terms_acceptance.ip).
A escrita é merge parcial: mande tudo de uma vez ou campo a campo, na ordem que a sua tela quiser.
Salvar não envia. O envio é explícito — o que permite autossalvar cada campo sem consumir uma tentativa de análise.

activation_status não é o status da conexão com a plataforma. not_submitted, in_review e disabled continuam pertencendo à mesma organização conectada. Corrija e reenvie o mesmo org_*; não crie uma conta duplicada.

Passo a passo (organização CNPJ)

1. Crie 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"
  }'

Guarde o id (org_*) — ele é o identificador estável do vendedor no seu sistema. Repetir a chamada com o mesmo documento devolve a mesma organização. A resposta já traz a lista de tarefas:

{
  "id": "org_Tm6DzHLoHTme9y47",
  "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-07-23T14:00:00Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": null,
  "individual": null,
  "livemode": true,
  "metadata": {},
  "name": "Acme",
  "payout_account": null,
  "platform": "plat_n5aNBQBXiqvYWPt4",
  "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-07-23T14:00:00Z",
  "website": null
}

A organização pode nascer active com requirements.missing vazio: o CPF/CNPJ dela já tinha um cadastro aprovado e o status é do documento. Nesse caso não há nada a coletar nem a enviar — pule direto para operar a organização.

2. Releia `requirements.missing` antes de montar a tela

Em organizações CNPJ, a Chargefy completa os dados públicos da empresa (razão social, nome fantasia, endereço, data de abertura e, quando existem no registro, e-mail e telefone) logo após a criação, a partir do registro público do CNPJ. Isso acontece em segundo plano: a resposta do create ainda mostra company: null, mas uma leitura seguinte costuma vir com o bloco preenchido e com menos itens em missing.

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

{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "company": {
    "address": {
      "city": "São Paulo",
      "line1": "Avenida Paulista",
      "line2": "Conjunto 101",
      "neighborhood": "Bela Vista",
      "number": "1000",
      "postal_code": "01310100",
      "state": "SP"
    },
    "email": "financeiro@meusite.com",
    "name": "ACME COMERCIO LTDA",
    "opening_date": "2019-03-14",
    "phone": "11999999999",
    "trade_name": "Acme"
  },
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "business_profile.annual_revenue",
      "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": []
  }
}

Use missing como fonte da sua tela: peça só o que está na lista. Você pode sobrescrever qualquer campo preenchido automaticamente — o que você grava sempre vence.

Se essa consulta responder 404, confirme o org_*, o ambiente da API key e se a conexão com a plataforma continua ativa. Adicionar o header Organization não corrige esse erro, porque o alvo já está na URL.

3. Complete os dados da empresa

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile": {
      "annual_revenue": {
        "amount": 120000000,
        "currency": "brl"
      },
      "url": "https://meusite.com"
    },
    "company": {
      "address": {
        "city": "São Paulo",
        "line1": "Avenida Paulista",
        "line2": "Conjunto 101",
        "neighborhood": "Bela Vista",
        "number": "1000",
        "postal_code": "01310100",
        "state": "SP"
      },
      "email": "financeiro@meusite.com",
      "name": "ACME COMERCIO LTDA",
      "opening_date": "2019-03-14",
      "phone": "+5511999999999",
      "trade_name": "Acme"
    },
    "statement_descriptor": "ACME"
  }'

O que vale saber:

business_profile.annual_revenue.amount é em centavos e currency é sempre "brl". business_profile.mcc é somente leitura: a categoria do negócio é resolvida pela Chargefy a partir do registro público do CNPJ.
statement_descriptor é o nome que aparece na fatura do comprador. Ele é normalizado (maiúsculas, letras, números e espaços) e precisa ficar entre 5 e 22 caracteres depois da normalização. É uma propriedade do documento fiscal: ao alterar, o novo valor passa a valer para todas as cobranças daquele CPF/CNPJ.
Endereço é atômico: quando enviado, é validado inteiro e substitui o anterior. line1, number, neighborhood, city, state (2 letras) e postal_code (8 dígitos) são obrigatórios; line2 é opcional.
Telefone aceita formatação livre e é guardado normalizado (DDD + número).

A resposta vem com missing menor:

{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "representative.address",
      "representative.birthdate",
      "representative.document",
      "representative.email",
      "representative.first_name",
      "representative.last_name",
      "representative.phone",
      "representative.verification.document",
      "representative.verification.selfie",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  }
}

4. Complete os dados do responsável

O responsável é a pessoa física que responde legalmente pela empresa.

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "document": "12345678901",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888"
    }
  }'

first_name e last_name precisam ser o nome civil da pessoa: nomes com números ou com termos de razão social (Ltda, EIRELI, Sociedade) são recusados com 400. document é o CPF do responsável, com ou sem pontuação. Sobram os arquivos, a conta e o aceite:

{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "representative.verification.document",
      "representative.verification.selfie",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  }
}

5. Suba os arquivos de verificação

Antes de implementar a tela de anexos, defina quem será verificado:

Organização filha	Pessoa verificada	De quem devem ser a selfie e o documento
CPF	O próprio titular	Do titular
CNPJ	O responsável legal informado em `representative`	Do responsável legal

Peça sempre uma selfie separada e apenas uma das opções de documento:

Opção	Arquivos do documento	Como anexar na API	Total com a selfie
CNH digital	1 PDF oficial exportado do app CNH Digital	`type: "cnh"`, use `front` e omita `back`	2
CNH frente e verso	1 arquivo da frente + 1 arquivo do verso da CNH física	`type: "cnh"`, use `front` e `back`	3
RG frente e verso	1 arquivo da frente + 1 arquivo do verso	`type: "rg"`, use `front` e `back`	3
CREF completo	1 arquivo da carteira aberta, com frente e verso visíveis	`type: "cref"`, use `front` e omita `back`	2
CREF frente e verso	1 arquivo da frente + 1 arquivo do verso	`type: "cref"`, use `front` e `back`	3
CIN digital	1 PDF oficial exportado do app gov.br	`type: "cin"`, use `front` e omita `back`	2
CIN frente e verso	1 arquivo da frente + 1 arquivo do verso	`type: "cin"`, use `front` e `back`	3
Passaporte	1 arquivo da página de identificação	`type: "passport"`, use `front` e omita `back`	2

As combinações inválidas falham na declaração, com 400 e param no campo exato: rg exige back; passport não aceita back; cnh ou cin com front único representam o documento digital e exigem o PDF oficial do app do governo — para fotos do documento físico, envie front e back.

A ativação atual não solicita upload de comprovante de endereço, contrato social, Requerimento de Empresário, comprovante de renda, documentos dos demais sócios ou comprovante bancário. Endereços e dados da conta para saques são preenchidos nos campos da organização.

Documento de identidade e selfie sobem por POST /v1/files com purpose=kyc_document. Com API key de plataforma, aponte a organização dona do arquivo no header Organization.

Nunca exponha a API key da plataforma no navegador. Envie o arquivo da sua interface para o backend da plataforma e faça o upload para a Chargefy a partir dele. Depois de receber o file_*, descarte a cópia temporária.

curl -X POST "https://api.chargefy.io/v1/files" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_Tm6DzHLoHTme9y47" \
  -F "purpose=kyc_document" \
  -F "file=@/caminho/local/documento-frente.jpg"

{
  "id": "file_B3cAGJDsoPoGF32Z",
  "object": "file",
  "created_at": "2026-07-23T14:01:00Z",
  "filename": "documento-frente.jpg",
  "mime_type": "image/jpeg",
  "purpose": "kyc_document",
  "size": 184320,
  "...": "demais campos do objeto file"
}

Guarde o id (file_*) — é ele que você anexa ao cadastro no passo seguinte. Faça um upload separado para cada posição indicada na tabela. A selfie aceita JPG, JPEG, PNG, WebP, BMP, HEIC e HEIF — nunca PDF. Os arquivos de documento aceitam os mesmos formatos e também PDF, com duas exceções: a CNH digital e a CIN digital aceitam somente o PDF oficial do app do governo (CNH Digital e gov.br, com QR code). Imagens podem ter até 20 MB e são normalizadas automaticamente para menos de 4,5 MB; PDFs podem ter até 5 MB e são armazenados sem recompressão. Arquivos de verificação são privados: a url do arquivo é assinada e expira em 1 hora — o cadastro não precisa dela.

Para o documento, use uma imagem do original válido e colorido, com todas as bordas e dados legíveis, sem cortes, reflexos, sombras, inclinação, dedos ou objetos cobrindo informações. Para a selfie, use boa iluminação, fundo neutro, rosto centralizado e sem filtros. A pessoa não deve segurar o documento na selfie.

Veja também a página que você pode compartilhar com o vendedor: Documentos de verificação aceitos.

6. Anexe os arquivos ao cadastro

O bloco depende da opção escolhida. Nos exemplos de CNPJ abaixo, ele fica em representative.verification. Para uma organização CPF, use o mesmo conteúdo em individual.verification.

CNH digital

Use front para o PDF oficial exportado do app CNH Digital e omita back.

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cnh"
        },
        "selfie": "file_vcqeVUqwgGApyUC9"
      }
    }
  }'

CNH frente e verso

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_vcqeVUqwgGApyUC9",
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cnh"
        },
        "selfie": "file_bLGr3spyEqPe1WKr"
      }
    }
  }'

RG frente e verso

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_vcqeVUqwgGApyUC9",
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "rg"
        },
        "selfie": "file_bLGr3spyEqPe1WKr"
      }
    }
  }'

CREF completo

Use front para o arquivo único da carteira aberta, em imagem ou PDF, e omita back.

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cref"
        },
        "selfie": "file_vcqeVUqwgGApyUC9"
      }
    }
  }'

CREF frente e verso

Use dois arquivos separados quando a carteira não estiver aberta em um único arquivo.

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_vcqeVUqwgGApyUC9",
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cref"
        },
        "selfie": "file_bLGr3spyEqPe1WKr"
      }
    }
  }'

CIN digital

Use front para o PDF oficial exportado do app gov.br e omita back.

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cin"
        },
        "selfie": "file_vcqeVUqwgGApyUC9"
      }
    }
  }'

CIN frente e verso

Use dois arquivos separados para a CIN física.

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_vcqeVUqwgGApyUC9",
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cin"
        },
        "selfie": "file_bLGr3spyEqPe1WKr"
      }
    }
  }'

Passaporte

Use front para a imagem da página de identificação. back não é aceito para passaporte.

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "passport"
        },
        "selfie": "file_vcqeVUqwgGApyUC9"
      }
    }
  }'

type aceita cnh, rg, cref, cin e passport. CNH e CIN aceitam o PDF oficial do documento digital em front ou as duas fotos do documento físico em front e back. O RG exige os dois lados. O CREF aceita a carteira aberta em front ou os dois lados em front e back. O passaporte usa somente front.
O bloco document é atômico: reenviá-lo substitui frente, verso e tipo de uma vez.
Cada arquivo só pode ocupar um espaço: usar o mesmo arquivo (ou o mesmo conteúdo) como documento e selfie retorna 400.
As fotos nunca voltam no objeto organization. O progresso aparece em requirements.

7. Conta para saques e aceite dos termos

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_account": {
      "account_number": "1234567",
      "bank_code": "341",
      "routing_number": "0001",
      "type": "checking"
    },
    "terms_acceptance": {
      "accepted_at": "2026-07-23T13:58:12Z",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0"
    }
  }'

A resposta devolve a organização com o bloco payout_account já resolvido — incluindo bank_name, derivado do bank_code (confira se o banco é o esperado antes de submeter):

{
  "payout_account": {
    "id": "pa_8gqQH2RWZi27y1sZ",
    "object": "payout_account",
    "account_number_last4": "4567",
    "bank_code": "341",
    "bank_name": "Itaú Unibanco S.A.",
    "...": "demais campos do objeto payout_account"
  }
}

A conta é atômica: os quatro campos vão juntos. O titular nunca é enviado — é sempre a identidade da organização.
terms_acceptance é o registro de que o vendedor aceitou os termos de serviço da Chargefy no seu produto: quando (accepted_at, no passado) e de onde (ip). user_agent é opcional e recomendado.

Agora missing está vazio — o cadastro está pronto, esperando o envio:

{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "activation_status": "not_submitted",
  "activation_submitted_at": null,
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [],
    "pending_verification": []
  }
}

8. Envie para análise

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

{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "activation_status": "in_review",
  "activation_submitted_at": "2026-07-23T14:02:00Z",
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [],
    "pending_verification": []
  }
}

Comportamento do envio:

Faltou campo → 400 com code: "requirements_incomplete", param no primeiro caminho e a lista completa em message.
Já enviado → 200 com o objeto atual. Organização in_review ou active não reenvia nada e não abre uma análise nova; repetir por timeout é seguro.
in_review significa “cadastro recebido”, não “aprovado”. Não libere recebimentos aqui.

Contrato completo: Enviar o cadastro.

9. Acompanhe o resultado por webhook

A análise é assíncrona (normalmente minutos). O veredito chega por organization.updated:

`activation_status`	O que significa	O que fazer
`in_review`	Cadastro recebido, análise em andamento.	Mostre “em análise”.
`active`	Aprovado.	Libere recebimentos.
`disabled`	Reprovado.	Leia `requirements` e ofereça a correção.
`not_submitted` (depois de um envio)	O envio falhou antes da análise.	`requirements.errors` explica; corrija e reenvie.

Aprovação:

{
  "id": "evt_YGcrStJSosTpw1F8",
  "object": "event",
  "created_at": "2026-07-23T15:30:00Z",
  "data": {
    "object": {
      "id": "org_Tm6DzHLoHTme9y47",
      "object": "organization",
      "...": "demais campos do objeto organization",
      "activation_status": "active",
      "requirements": {
        "disabled_reason": null,
        "errors": [],
        "missing": [],
        "pending_verification": []
      }
    },
    "previous_attributes": {
      "activation_status": "in_review"
    }
  },
  "livemode": true,
  "organization": "org_Tm6DzHLoHTme9y47",
  "request": {
    "id": "req_QLA3Wk2W4DieY219"
  },
  "type": "organization.updated"
}

Processe por id do evento (idempotência) e trate code desconhecido de forma genérica — o conjunto cresce.

Variante pessoa física (CPF)

Idêntico, com duas diferenças:

Não existe bloco company: a pessoa física é o próprio vendedor e todos os dados dela vão em individual.
individual.document não é aceito — o documento da organização já é o CPF dela. Enviar esse campo retorna 400.

curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "individual": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888"
    }
  }'

Os caminhos de missing acompanham: individual.address, individual.verification.selfie, e assim por diante. O resto do fluxo (arquivos, conta, aceite, envio) é igual.

{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "document_type": "cpf",
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "individual.verification.document",
      "individual.verification.selfie",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  }
}

O ciclo de correção

Reprovação não é fim de linha. Ela devolve os campos para requirements.missing e explica o motivo em requirements.errors[], onde requirement aponta o caminho exato que falhou:

{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "activation_status": "disabled",
  "requirements": {
    "disabled_reason": null,
    "errors": [
      {
        "code": "identity_name_mismatch",
        "message": "The name provided does not match the name registered for the taxpayer id.",
        "requirement": "representative.verification.document",
        "resolution": "Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt."
      }
    ],
    "missing": [
      "representative.first_name",
      "representative.last_name",
      "representative.verification.document"
    ],
    "pending_verification": []
  }
}

O ciclo é sempre o mesmo:

Mostre ao vendedor o que precisa mudar (use resolution, ou traduza a partir do code).
Regrave só os caminhos de missing com POST /v1/organizations/{id}.
Chame POST /v1/organizations/{id}/submit de novo — mesma organização, mesmo org_*. Nada do que você construiu em cima dela se perde.

Campos de verificação que não aparecem em missing continuam válidos e não precisam ser reenviados. Em identity_document_mismatch, por exemplo, faça o upload de outro documento e envie um novo verification.document; omita verification.selfie para manter a selfie atual. Se quiser substituí-la, envie também um novo file_* em verification.selfie. O arquivo recusado não é reaproveitado na nova análise. disabled_reason preenchido é terminal. "rejected.attempt_limit_reached" significa limite de tentativas esgotado; "rejected.other" significa que não há caminho de autoatendimento. Nos dois casos, encaminhe ao suporte e não reenvie em loop. Há também a falha de envio: quando o cadastro não chega a ser analisado (atividade econômica não suportada, arquivo apagado entre o envio e o processamento), a organização volta para not_submitted, activation_submitted_at volta para null e o motivo aparece em requirements.errors. Regravar qualquer bloco limpa esse erro. A tabela de códigos, os caminhos apontados por cada um e todas as variações de payload estão em Requisitos de ativação.

Modo de teste

Com credencial de teste (livemode: false), o cadastro roda ponta a ponta sem tocar em nenhum documento real. O desfecho é determinístico e escolhido pelo documento da organização — o mesmo recurso dos cartões de teste:

Documento da organização	Desfecho	O que você exercita
`00000000000` (CPF) ou `00000000000000` (CNPJ)	Aprovado	`in_review` → `active`
`11111111111` ou `11111111111111`	Reprovado com correção	`disabled` com `errors`, `missing` e `disabled_reason: null`
`22222222222` ou `22222222222222`	Reprovado sem autoatendimento	`disabled` com `disabled_reason: "rejected.other"`
Qualquer outro	Fica em análise	`in_review` indefinido

Os arquivos continuam sendo enviados de verdade por POST /v1/files (qualquer imagem válida serve) — o que muda é a análise, que responde pelo documento. Como os motivos de reprovação passam pelo mesmo tratamento da produção, você recebe os mesmos code, message e resolution que veria em uma conta real.

O que não fazer

Não chame /submit a cada campo salvo. Autossalve à vontade com POST /v1/organizations/{id}; envie uma vez, quando missing zerar. Depois de uma reprovação, cada reenvio consome uma das tentativas de reativação (atualmente 3).
Não crie outra organização porque o cadastro reprovou. O reenvio é sempre no mesmo org_* — outra organização espalha o histórico do vendedor.
Não confie em in_review para liberar recebimentos. Só active habilita a organização a receber.
Não monte a sua tela a partir de uma lista fixa de campos. Use requirements.missing: ele é a fonte, e muda com o tipo de documento e com o que já foi preenchido.
Não guarde as fotos no seu servidor. Suba direto por POST /v1/files e guarde apenas o file_*.
Não invente um quinto estado. São quatro: not_submitted, in_review, active, disabled.

Referências

Contrato de escrita: Atualizar organização · Enviar o cadastro
Objeto e leitura: organization · Consultar organização
Arquivos: Criar arquivo
Arquivos aceitos: Documentos de verificação aceitos
Resultado e pendências: Requisitos de ativação · organization.updated
Caminho hospedado: Ativação hospedada
Contexto de plataforma: Organizações conectadas · Reenviar KYC

Visão geral

Ativação de organizações

Modelo de negócio

Plataformas: guia completo de ativação por API

Os dois caminhos

Pré-requisitos

O modelo, em uma frase

Passo a passo (organização CNPJ)

1. Crie a organização conectada

2. Releia `requirements.missing` antes de montar a tela

3. Complete os dados da empresa

4. Complete os dados do responsável

5. Suba os arquivos de verificação

6. Anexe os arquivos ao cadastro

CNH digital

CNH frente e verso

RG frente e verso

CREF completo

CREF frente e verso

CIN digital

CIN frente e verso

Passaporte

7. Conta para saques e aceite dos termos

8. Envie para análise

9. Acompanhe o resultado por webhook

Variante pessoa física (CPF)

O ciclo de correção

Modo de teste

O que não fazer

Referências

​Os dois caminhos

​Pré-requisitos

​O modelo, em uma frase

​Passo a passo (organização CNPJ)

​1. Crie a organização conectada

​2. Releia requirements.missing antes de montar a tela

​3. Complete os dados da empresa

​4. Complete os dados do responsável

​5. Suba os arquivos de verificação

​6. Anexe os arquivos ao cadastro

​CNH digital

​CNH frente e verso

​RG frente e verso

​CREF completo

​CREF frente e verso

​CIN digital

​CIN frente e verso

​Passaporte

​7. Conta para saques e aceite dos termos

​8. Envie para análise

​9. Acompanhe o resultado por webhook

​Variante pessoa física (CPF)

​O ciclo de correção

​Modo de teste

​O que não fazer

​Referências

Os dois caminhos

Pré-requisitos

O modelo, em uma frase

Passo a passo (organização CNPJ)

1. Crie a organização conectada

2. Releia `requirements.missing` antes de montar a tela

3. Complete os dados da empresa

4. Complete os dados do responsável

5. Suba os arquivos de verificação

6. Anexe os arquivos ao cadastro

CNH digital

CNH frente e verso

RG frente e verso

CREF completo

CREF frente e verso

CIN digital

CIN frente e verso

Passaporte

7. Conta para saques e aceite dos termos

8. Envie para análise

9. Acompanhe o resultado por webhook

Variante pessoa física (CPF)

O ciclo de correção

Modo de teste

O que não fazer

Referências