Evento payout.account.detached

Evento `payout.account.detached`

Disparado quando uma payout_account é desconectada da organização atuante. O destino de repasses continua preservado no cadastro financeiro. Use este evento para remover o vínculo da conta na sua visão local, atualizar painéis de ativação e evitar que uma conta desconectada continue aparecendo como a conta principal da organização. data.object carrega a conta para saques envolvida na desconexão. O payload não traz número completo de conta; use account_number_last4, bank_code, routing_number e holder_name para identificação visual.

Desconectar não significa apagar todos os dados históricos associados ao pa_*. Para exibir a conta conectada atual da organização, consulte a organização ou reaja ao próximo evento que indique uma nova conta conectada.

Quando acontece

Situação	Como aparece no payload
Conta desconectada pela API	`type: "payout.account.detached"` e `data.object.id` identifica a conta.
Organização fica sem aquela conta conectada	O envelope top-level traz `organization` com a organização afetada.
Destino preservado no cadastro financeiro	O objeto `payout_account` ainda vem completo em `data.object`.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (pa_*) para localizar a conta que deixou de estar conectada.
Remova ou atualize o vínculo local entre a organização e a conta para saques.
Mantenha histórico financeiro associado ao pa_*; o evento indica desconexão, não necessariamente exclusão física do histórico.
Use account_number_last4 e holder_name para reconciliar a conta com segurança em telas internas.

Campos importantes

Campo	O que observar
`data.object.id`	Conta para saques que foi desconectada.
`organization`	Organização em que o vínculo foi encerrado.
`account_number_last4`	Identificador seguro para exibição da conta.
`bank_code` / `routing_number`	Banco e agência/roteamento da conta.
`holder_name`	Titular da conta desconectada.
`is_active`	Indica se a conta era a principal no cadastro financeiro; não confirma o crédito dos repasses.
`updated_at`	Última atualização conhecida da conta.

Tipos de conta

Valor	Descrição
`checking`	Conta corrente.
`savings`	Conta poupança.

Exemplo de payload

{
  "id": "evt_BPbk4GDHGxhoQao9",
  "object": "event",
  "created_at": "2026-05-16T15:00:00Z",
  "data": {
    "object": {
      "id": "pa_zGTqsNpMXCjvnKPA",
      "object": "payout_account",
      "account_number_last4": "5678",
      "bank_code": "001",
      "bank_name": "Banco Exemplo S.A.",
      "created_at": "2026-05-16T14:09:27Z",
      "holder_name": "Acme Ltda",
      "is_active": true,
      "is_verified": false,
      "livemode": true,
      "metadata": {},
      "routing_number": "0001",
      "type": "checking",
      "updated_at": "2026-05-16T14:20:00Z"
    }
  },
  "livemode": true,
  "organization": "org_Mqh2eepMG2mzG14P",
  "request": {
    "id": null
  },
  "type": "payout.account.detached"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento payout.account.detached