Evento organization.review.required

Evento `organization.review.required`

Disparado quando uma organização conectada precisa confirmar ou atualizar dados cadastrais para manter a conta apta a receber pagamentos. O evento é exclusivo do Chargefy for Platforms e é entregue somente aos endpoints da plataforma conectada com events_from: "platform" que assinaram esse tipo. Endpoints com events_from: "organization" não podem assiná-lo. Use data.object.url para levar o responsável pela conta ao fluxo hospedado de atualização cadastral.

organization.review.required indica que há uma ação pendente. A conta ainda pode estar operando normalmente, mas a atualização deve ser concluída dentro do prazo para evitar interrupções no recebimento de pagamentos.

Compartilhe data.object.url somente com o responsável pela organização. O link abre um fluxo hospedado para confirmar dados cadastrais e deve ser tratado como informação sensível.

Quando acontece

Situação	Como aparece no payload
Uma atualização cadastral foi solicitada	`data.object.status: "pending"` e `url` preenchida.
Há campos específicos solicitados	`requested_fields` lista os grupos de dados pedidos.
O fluxo exige preenchimento completo	`submission_mode: "full"`.
Há prazo recomendado para envio	`deadline_at` vem preenchido; quando `null`, use a validade operacional do link hospedado.
A solicitação tem um tipo normalizado	`review_type` pode vir como `periodic`, `inconsistent` ou `unknown`.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (sr_*) como chave da atualização cadastral no seu sistema.
Envie data.object.url ao responsável pela organização enquanto o status estiver pendente.
Use deadline_at para priorizar notificações e evitar atraso no envio.
Interprete requested_fields junto com submission_mode: em full, o fluxo pede todos os dados exigidos; em partial, foque nos campos listados.
Continue acompanhando organization.review.submitted e organization.updated para saber quando o envio ocorrer e se dados públicos mudarem.

O objeto da revisão tem ID sr_*, mas a conta conectada é o org_* do campo top-level organization. Para reler a conta, use GET /v1/organizations/{organization} sem o header Organization.

Campos importantes

Campo	O que observar
`data.object.status`	Estado atual da atualização cadastral.
`url`	Link hospedado que deve ser compartilhado com o responsável pela organização.
`deadline_at`	Prazo recomendado para envio, quando existir.
`requested_fields`	Campos ou grupos de dados solicitados no processo.
`submission_mode`	Define se o preenchimento esperado é completo ou parcial.
`review_type`	Motivo normalizado da atualização cadastral.
`submitted_at`	Normalmente `null` neste evento, pois o envio ainda não ocorreu.
`organization`	Organização conectada que precisa concluir a atualização.

Status possíveis

Valor	Descrição
`pending`	Atualização aguardando envio pela organização.
`overdue`	Envio em atraso em relação ao prazo.
`expired`	Janela de envio expirou sem conclusão.
`submitted`	Dados enviados, aguardando análise.
`finished`	Processo de atualização concluído.
`failed`	O envio não pôde ser processado; é necessário enviar novamente.

Tipos e modos

Campo	Valores
`review_type`	`periodic`, `inconsistent` ou `unknown`.
`submission_mode`	`full`, `partial` ou `unknown`.

Exemplo de payload

{
  "id": "evt_zZdPdvjbQi4WaK6F",
  "object": "event",
  "created_at": "2026-06-24T12:00:00.000Z",
  "data": {
    "object": {
      "id": "sr_gBb1eLALKdsGjag8",
      "object": "organization_review",
      "created_at": "2026-06-24T12:00:00.000Z",
      "deadline_at": "2026-07-24T12:00:00.000Z",
      "livemode": true,
      "metadata": {},
      "organization": "org_ZJN6rNhyAuHaMEBu",
      "requested_fields": [
        "revenue",
        "address"
      ],
      "review_type": "periodic",
      "status": "pending",
      "submission_mode": "full",
      "submitted_at": null,
      "updated_at": "2026-06-24T12:00:00.000Z",
      "url": "https://hosted.chargefy.io/review/UpBCTlVOgL7BuWIrbW5rdAmZaeF14bQ1x9Fy_QgndQQ"
    }
  },
  "livemode": true,
  "organization": "org_ZJN6rNhyAuHaMEBu",
  "request": {
    "id": null
  },
  "type": "organization.review.required"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento organization.review.required