Skip to main content
curl -X POST "https://api.chargefy.io/v1/onboarding-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "org_789",
    "return_url": "https://example.com/onboarding/return"
  }'

{
  "id": "os_123",
  "object": "onboarding_session",
  "created_at": "2026-04-30T18:30:00Z",
  "expires_at": "2026-04-30T18:31:00Z",
  "livemode": true,
  "metadata": {},
  "opened_at": null,
  "organization": "org_789",
  "platform": "plat_456",
  "return_url": "https://meusite.com/onboarding/return",
  "status": "created",
  "updated_at": "2026-04-30T18:30:00Z",
  "url": "https://hosted.chargefy.io/onboarding/os_123?authorization_code=..."
}
Cria ou renova uma sessão hospedada para ativar o perfil financeiro de uma organização conectada existente. Envie o organization; a Chargefy usa os dados fiscais cadastrados nessa organização para abrir o fluxo hospedado. Chamadas repetidas para a mesma organização devolvem o mesmo id de onboarding_session, com uma URL fresca por 60 segundos.

​
Autenticação

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

​
Attributes

​
organization
string
required
ID da organização conectada (org_*) que será ativada financeiramente.
​
metadata
object
Mapa opcional string → string com até 50 chaves. Ecoado em data.object.metadata no webhook onboarding.session.submitted. Chaves: [a-zA-Z0-9_\-.]{1,40}. Valores: até 500 caracteres.
​
return_url
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.
curl -X POST "https://api.chargefy.io/v1/onboarding-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "org_789",
    "return_url": "https://example.com/onboarding/return"
  }'

​
Resposta

A resposta é o recurso onboarding_session.
​
id
string
ID do onboarding session (os_*).
​
object
string
Sempre "onboarding_session".
​
created_at
string
Quando o onboarding session foi criado.
​
expires_at
string | null
ISO 8601 do momento em que a URL expira. null quando não há URL ativa.
​
livemode
boolean
true quando o onboarding session foi criado com credencial de produção.
​
metadata
object
Eco do metadata enviado na criação.
​
opened_at
string | null
Quando o vendedor abriu o fluxo hospedado pela primeira vez.
​
organization
string
ID canônico da organização conectada (org_*).
​
platform
string
ID da sua plataforma (plat_*).
​
return_url
string
URL de retorno configurada na criação.
​
status
string
created, in_progress, submitted, failed ou expired.
​
updated_at
string | null
Última modificação do onboarding session.
​
url
string | null
URL com authorization_code de uso único, válido por 60 segundos.
{
  "id": "os_123",
  "object": "onboarding_session",
  "created_at": "2026-04-30T18:30:00Z",
  "expires_at": "2026-04-30T18:31:00Z",
  "livemode": true,
  "metadata": {},
  "opened_at": null,
  "organization": "org_789",
  "platform": "plat_456",
  "return_url": "https://meusite.com/onboarding/return",
  "status": "created",
  "updated_at": "2026-04-30T18:30:00Z",
  "url": "https://hosted.chargefy.io/onboarding/os_123?authorization_code=..."
}

​
Regras

  • organization.activation_status = active: não cria nova sessão; a organização já está apta a operar.
  • organization.activation_status = pending: não cria nova sessão; aguarde o próximo organization.updated.
  • organization.activation_status = activation_pending: cria ou renova o link normalmente.
  • organization.activation_status = disabled: cria ou renova uma nova tentativa para a mesma organização.
disabled não é terminal para a organização. Ele significa que o perfil financeiro atual não está apto; uma nova tentativa de onboarding pode criar um novo perfil financeiro interno mantendo o mesmo org_*.

​
Erros

StatusQuando
400Payload inválido (organization, return_url, metadata).
401API key ausente, inválida, revogada ou expirada.
403API key sem escopo platform_admin.
404Organização conectada não encontrada para a plataforma.
409Platform inativa, setup incompleto, org ativa ou org pendente.
422A 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.