Criar uma sessão de ativação

curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "org_wkPueRS5fh1GMMij",
    "return_url": "https://meusite.com/activation/return"
  }'

curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {},
    "organization": "org_wkPueRS5fh1GMMij",
    "return_url": "https://meusite.com/activation/return"
  }'

{
  "id": "as_t6HURw6ftTuv13Gm",
  "object": "activation_session",
  "created_at": "2026-04-30T18:30:00Z",
  "expires_at": "2026-04-30T18:31:00Z",
  "livemode": true,
  "metadata": {},
  "opened_at": null,
  "organization": "org_wkPueRS5fh1GMMij",
  "platform": "plat_kQdRy4YQq22MA7Gy",
  "return_url": "https://meusite.com/activation/return",
  "status": "created",
  "updated_at": "2026-04-30T18:30:00Z",
  "url": "https://hosted.chargefy.io/activation/as_t6HURw6ftTuv13Gm?authorization_code=..."
}

Cria ou renova uma sessão hospedada para ativar o perfil financeiro de uma organização conectada a uma plataforma. Envie o organization; a Chargefy usa os dados fiscais cadastrados nessa organização para abrir o fluxo hospedado. Apenas organization e return_url são obrigatórios. metadata é opcional, e URL, expiração e status são resolvidos pela Chargefy. Cada sessão representa uma tentativa de cadastro:

se já existe uma sessão aberta (created ou in_progress), o POST devolve o mesmo as_* com uma URL nova;
depois de submitted, essa tentativa não é reaberta;
se a organização puder tentar novamente, o próximo POST cria outro activation_session, com outro as_*.

A organização continua com o mesmo org_* em todas as tentativas.

Autenticação

API key de plataforma com escopo administrativo via header Authorization: Bearer {{PLATFORM_API_KEY}}.

Attributes

object

Mapa opcional string → string com até 50 chaves. Ecoado em metadata quando você consulta a sessão. Chaves: [a-zA-Z0-9_\-.]{1,40}. Valores: até 500 caracteres. Padrão: {}.

string

required

ID da organização conectada (org_*) que será ativada financeiramente.

string

required

URL para onde o vendedor volta ao concluir ou sair do cadastro. Deve ser http:// ou https:// e ter no máximo 2048 caracteres.

O que a Chargefy resolve sozinha

Uma sessão aberta por organização — enquanto a tentativa estiver aberta, repetir o POST devolve o mesmo as_*. Uma nova tentativa recebe outro as_*; use o org_* como identificador estável da conta.
Etapas de ativação — a Chargefy determina automaticamente o que precisa ser revisado ou preenchido e apresenta apenas as etapas necessárias no fluxo hospedado.
url e expires_at — a cada POST, uma URL nova é emitida com authorization_code de uso único, válido por 60 segundos.
Dados fiscais — o documento vem do cadastro da organização; sem documento válido, a criação retorna 422.

curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "org_wkPueRS5fh1GMMij",
    "return_url": "https://meusite.com/activation/return"
  }'

curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {},
    "organization": "org_wkPueRS5fh1GMMij",
    "return_url": "https://meusite.com/activation/return"
  }'

Resposta

A resposta é o recurso activation_session.

string

ID da sessão de ativação (as_*).

string

Sempre "activation_session".

string

Quando a sessão de ativação foi criada.

string | null

ISO 8601 do momento em que a URL expira. null quando não há URL ativa.

boolean

true quando a sessão de ativação foi criada com credencial de produção.

object

Eco do metadata enviado na criação.

string | null

Quando o vendedor abriu o fluxo hospedado pela primeira vez.

string

ID canônico da organização conectada (org_*).

string

ID da sua plataforma (plat_*).

string

URL de retorno configurada na criação.

string

Estado da sessão.

Valor	Descrição
`created`	Sessão criada; o fluxo hospedado ainda não foi aberto.
`in_progress`	O vendedor abriu o fluxo hospedado e está preenchendo.
`submitted`	Formulário enviado. Aprovação e reprovação pertencem à `organization`.

string | null

Última modificação da sessão de ativação.

string | null

URL com authorization_code de uso único, válido por 60 segundos.

{
  "id": "as_t6HURw6ftTuv13Gm",
  "object": "activation_session",
  "created_at": "2026-04-30T18:30:00Z",
  "expires_at": "2026-04-30T18:31:00Z",
  "livemode": true,
  "metadata": {},
  "opened_at": null,
  "organization": "org_wkPueRS5fh1GMMij",
  "platform": "plat_kQdRy4YQq22MA7Gy",
  "return_url": "https://meusite.com/activation/return",
  "status": "created",
  "updated_at": "2026-04-30T18:30:00Z",
  "url": "https://hosted.chargefy.io/activation/as_t6HURw6ftTuv13Gm?authorization_code=..."
}

Regras

organization.activation_status = active: não cria nova sessão; a organização já está apta a operar.
organization.activation_status = in_review: não cria nova sessão; aguarde o próximo organization.updated.
organization.activation_status = not_submitted: cria ou renova o link normalmente.
organization.activation_status = disabled: cria uma nova sessão para a mesma organização, desde que requirements.disabled_reason esteja null e o limite de tentativas não tenha sido atingido. Os dados já salvos na organização podem ser usados no preenchimento.

disabled não é definitivo para a organização. Ele significa que o perfil financeiro atual não está apto; uma nova tentativa de ativação pode reiniciar o cadastro mantendo o mesmo org_*. Antes de reenviar, leia organization.requirements e oriente a correção pelos caminhos em missing — o fluxo completo está em Requisitos de ativação.

Erros

Status	`code`	Quando
`400`	`invalid_request`	Payload inválido (`organization`, `return_url`, `metadata`).
`401`	`authentication_failed`	API key ausente, inválida, revogada ou expirada.
`403`	`permission_denied`	API key sem escopo administrativo da plataforma.
`404`	`resource_missing`	Organização conectada não encontrada para a plataforma.
`409`	`resource_state_conflict`	Plataforma inativa ou configuração incompleta.
`409`	`organization_already_active`	Organização já ativada.
`409`	`organization_activation_in_review`	Organização já está em análise.
`409`	`activation_not_retryable`	`requirements.disabled_reason` preenchido: sem caminho de reenvio ou limite de tentativas atingido.
`409`	`document_already_in_use`	O documento não pode ser usado nesta ativação.
`422`	`organization_document_required`	A organização ainda não tem documento fiscal válido.

Para consultar o estado financeiro atual, use GET /v1/organizations/{id}. Para receber mudanças em tempo real, escute organization.updated.

curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "org_wkPueRS5fh1GMMij",
    "return_url": "https://meusite.com/activation/return"
  }'

curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {},
    "organization": "org_wkPueRS5fh1GMMij",
    "return_url": "https://meusite.com/activation/return"
  }'

{
  "id": "as_t6HURw6ftTuv13Gm",
  "object": "activation_session",
  "created_at": "2026-04-30T18:30:00Z",
  "expires_at": "2026-04-30T18:31:00Z",
  "livemode": true,
  "metadata": {},
  "opened_at": null,
  "organization": "org_wkPueRS5fh1GMMij",
  "platform": "plat_kQdRy4YQq22MA7Gy",
  "return_url": "https://meusite.com/activation/return",
  "status": "created",
  "updated_at": "2026-04-30T18:30:00Z",
  "url": "https://hosted.chargefy.io/activation/as_t6HURw6ftTuv13Gm?authorization_code=..."
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Criar uma sessão de ativação

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Regras

Erros

​Autenticação

​Attributes

​O que a Chargefy resolve sozinha

​Resposta

​Regras

​Erros

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Regras

Erros