Pular para o conteúdo principal

Evento organization.updated

Disparado para a organização da plataforma quando uma organização conectada muda em um campo público relevante. Isso inclui status de ativação financeira, a lista de tarefas da ativação (requirements), conta para saques ativa, dados cadastrais, endereço de cobrança, marca (branding_settings) e metadata da relação com a plataforma. Também dispara quando o plano de taxas da organização muda (fee_plan). Trocar o plano padrão da plataforma não gera este evento: as organizações já criadas mantêm o plano que tinham. O evento também dispara quando apenas o motivo muda: se a organização já estava disabled e a análise adiciona ou refina uma pendência, chega um novo organization.updated com previous_attributes.requirements — mesmo com activation_status inalterado. Quando os pagamentos são bloqueados, data.object.requirements.disabled_reason passa a blocked.payments. Quando o acesso da conta é bloqueado, o valor passa a blocked.account. Se o bloqueio voltar ao nível de pagamentos, o valor volta a blocked.payments. A liberação completa devolve o motivo vigente do cadastro financeiro ou null. Cada transição inclui o requirements anterior em data.previous_attributes. O cadastro financeiro determina activation_status. data.object carrega o estado atual completo da organização conectada (incluindo activation_status e payout_account quando preenchidos), e data.previous_attributes mostra o valor anterior dos campos que mudaram — útil pra detectar transições. Quando requirements muda, o diff traz o objeto anterior completo. Use este evento para sincronizar o admin da plataforma sem precisar buscar a organização novamente. Quando a conta para saques ativa muda, data.object.payout_account traz a conta atual e data.previous_attributes.payout_account traz a conta anterior.
O payload em data.object é sempre o estado completo e atual. Use data.previous_attributes apenas para saber o que mudou; a fonte do estado final é data.object.
activation_status: "disabled" significa que o perfil financeiro não está apto; não significa que a organização foi desconectada da plataforma. Corrija e reenvie a mesma org_* em vez de criar uma organização duplicada.

Quando acontece

Como processar

  • Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
  • Use data.object.id (org_*) para atualizar o registro local da organização conectada.
  • Aplique o estado completo de data.object; não reconstrua estado final apenas pelo diff.
  • Use data.previous_attributes para auditoria, notificações e regras condicionais de transição.
  • Libere recebimentos quando activation_status estiver active; bloqueie quando estiver disabled.
  • Em not_submitted após um envio, leia requirements.errors, corrija os caminhos de missing e chame /submit novamente na mesma organização.
  • Em disabled, decida pelo requirements: se disabled_reason vier null, corrija os caminhos em missing e inicie outra tentativa na mesma organização — outra activation session no hospedado, ou atualização + /submit pela API. Se disabled_reason vier preenchido, o caso é terminal: encaminhe ao suporte e não repita automaticamente. "under_review" indica conta já aprovada que foi suspensa depois, por segurança, sem nada a corrigir.
  • Exiba message/resolution de cada erro como estão (inglês) ou traduza a partir do code; trate code desconhecido de forma genérica.
  • Atualize a conta exibida no admin usando somente os dados públicos de payout_account, como account_number_last4.
  • Trate ausência de uma chave em previous_attributes como “campo não mudou”.
O envelope organization e data.object.id identificam a mesma conta. Se precisar confirmar o estado mais recente, chame GET /v1/organizations/ {organization} sem o header Organization.

Campos importantes

Status financeiros

Exemplo: plano de taxas mudou

A plataforma trocou o plano de uma organização do padrão (plan_nVTh3XtU, com a tabela de juros 00349) para plan_k6F3mqMZ, que usa a tabela 00299. A tabela vem com o plano, então o diff carrega os dois campos:

Exemplo: marca mudou

A plataforma trocou a aparência de uma organização filha com POST /v1/organizations/{id}: o botão passou do índigo do catálogo para o verde #278629 da marca, o painel do produto ganhou o fundo #F6F9FC e o estilo passou de ellipse para squircle. O diff traz o bloco branding_settings anterior completo, não só as chaves que mudaram:
Quando a organização deixa de ter aparência própria (appearance: null), previous_attributes.branding_settings traz o bloco que ela tinha. O caminho inverso também aparece: uma organização que seguia a plataforma e ganhou aparência própria chega com previous_attributes.branding_settings igual a { "appearance": null }. Mudar a aparência da própria plataforma não gera este evento nas organizações filhas que a seguem: o que elas salvaram continua appearance: null.

Exemplo: envio falhou antes da análise

Quando uma submissão feita pela API falha antes de entrar na análise, o evento informa a volta para not_submitted e mantém o motivo acionável no objeto atual:

Exemplo: cadastro aprovado

previous_attributes.requirements traz o objeto anterior completo — durante a análise, pending_verification listava o que estava sendo verificado. Ausência de uma chave no diff significa “campo não mudou”.

Exemplo: cadastro reprovado

disabled_reason: null indica que há caminho de correção: os caminhos em missing dizem o que recoletar. Depois, inicie outra tentativa na mesma organização pelo canal da integração — outra activation session no hospedado, ou atualização + /submit pela API.

Exemplo: motivo mudou, status não

Quando a análise adiciona ou refina uma pendência de uma organização que já estava disabled, o diff carrega apenas requirements: