> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> O objeto Onboarding Session

Uma `onboarding_session` representa uma sessão hospedada para ativar ou
reativar o perfil financeiro de uma `organization` conectada. A sessão pertence
a uma plataforma, aponta para uma organização existente e entrega uma URL
temporária para o fluxo hospedado.

O status financeiro não fica no objeto `onboarding_session`. Consulte
[`GET /v1/organizations/{id}`](/api-reference/organizations/get) ou acompanhe
[`organization.updated`](/api-reference/webhooks/organization.updated) para ler
`organization.activation_status`.

## Data Object

Este é o formato completo retornado em `create`, `get` e em `data.object` do
webhook `onboarding.session.submitted`.

```json theme={}
{
  "id": "os_123",
  "object": "onboarding_session",
  "created_at": "2026-05-16T14:09:27Z",
  "expires_at": "2026-05-16T14:10:27Z",
  "livemode": true,
  "metadata": {},
  "opened_at": null,
  "organization": "org_789",
  "platform": "plat_456",
  "return_url": "https://meusite.com/onboarding/return",
  "status": "created",
  "updated_at": "2026-05-16T14:09:27Z",
  "url": "https://hosted.chargefy.io/onboarding/os_123?authorization_code={{AUTHORIZATION_CODE}}"
}
```

<ResponseField name="id" type="string">
  Identificador da onboarding session. Usa o prefixo `os_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"onboarding_session"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em ISO 8601.
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  Data de expiração da URL em ISO 8601. No `GET` e em estados fechados, vem
  `null`.
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` em produção; `false` em ambiente de teste.
</ResponseField>

<ResponseField name="metadata" type="object">
  Metadata enviada na criação desta onboarding session. Retorna `{}` quando
  vazia.
</ResponseField>

<ResponseField name="opened_at" type="string | null">
  Quando o usuário abriu o fluxo hospedado pela primeira vez.
</ResponseField>

<ResponseField name="organization" type="string">
  ID canônico da organização conectada existente (`org_*`).
</ResponseField>

<ResponseField name="platform" type="string">
  ID da plataforma dona da sessão.
</ResponseField>

<ResponseField name="return_url" type="string">
  URL para onde o usuário volta ao concluir ou sair do fluxo hospedado.
</ResponseField>

<ResponseField name="status" type="string">
  Estado da sessão: `created`, `in_progress`, `submitted`, `failed` ou
  `expired`.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em ISO 8601.
</ResponseField>

<ResponseField name="url" type="string | null">
  URL hospedada com `authorization_code` de uso único. No `GET` e em estados
  fechados, vem `null`.
</ResponseField>

## Operações

* [Criar onboarding session](/api-reference/onboarding-sessions/create)
* [Consultar onboarding session](/api-reference/onboarding-sessions/get)

## Webhooks

* [`onboarding.session.submitted`](/api-reference/webhooks/onboarding.session.submitted)
* [`organization.updated`](/api-reference/webhooks/organization.updated)

`onboarding.session.submitted` informa que a sessão foi enviada. O resultado
financeiro chega pela organização conectada.