Evento organization.updated

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, branding e metadata da relação com a plataforma. 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. 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

Situação	Como aparece no payload
Cadastro financeiro foi aprovado	`activation_status` muda para `active`, `requirements` fica todo vazio e os valores anteriores aparecem em `previous_attributes`.
Cadastro financeiro entrou em análise	`activation_status` muda para `in_review` e `requirements.pending_verification` lista o que está sendo verificado.
Envio por API falhou antes da análise	`activation_status` volta de `in_review` para `not_submitted`; `requirements.errors` explica o motivo e `missing` aponta a correção.
Perfil financeiro deixou de estar apto	`activation_status` muda para `disabled`; `requirements.errors` traz os motivos e `requirements.missing` o que é corrigível.
A análise detalhou ou mudou o motivo da reprovação	`requirements` muda e o objeto anterior aparece em `previous_attributes.requirements`, mesmo com `activation_status` inalterado.
Nova tentativa de ativação foi enviada após reprovação	`activation_status` volta para `in_review` e `requirements.errors` fica `[]`; os valores anteriores aparecem no diff.
Conta para saques ativa mudou	`data.object.payout_account` traz a conta atual e `previous_attributes.payout_account` traz a anterior.
Dados públicos foram atualizados	Campos como `name`, `email`, `billing_address`, `branding_settings` ou `metadata` podem aparecer no diff.

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.
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

Campo	O que observar
`data.object.activation_status`	Status financeiro atual da organização conectada.
`data.object.requirements`	Lista de tarefas da ativação: `disabled_reason`, `errors`, `missing`, `pending_verification`. Tudo vazio quando não há pendência.
`activation_status_updated_at`	Momento da última mudança de status financeiro.
`activation_submitted_at`	Quando o cadastro foi enviado para análise.
`data.previous_attributes`	Campos alterados com seus valores anteriores.
`payout_account`	Conta para saques ativa atual, sem número completo da conta.
`billing_address` / `billing_name`	Dados de cobrança atuais da organização.
`branding_settings`	Identidade visual atual de invoices e do portal do cliente.
`metadata`	Metadata pública do vínculo entre plataforma e organização conectada.
`platform`	ID da plataforma que recebe o evento.

Status financeiros

Valor	Descrição
`not_submitted`	O cadastro ainda não foi enviado ou o último envio falhou antes da análise. Veja `requirements`.
`in_review`	Cadastro enviado e em análise.
`active`	Perfil financeiro aprovado e apto a receber pagamentos.
`disabled`	O perfil financeiro atual não está apto. Veja `requirements`.

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:

{
  "id": "evt_YGcrStJSosTpw1F8",
  "object": "event",
  "created_at": "2026-08-11T14:02:30.000Z",
  "data": {
    "object": {
      "id": "org_nCotBVzuEaMi3nbW",
      "object": "organization",
      "...": "demais campos da organization",
      "activation_status": "not_submitted",
      "activation_status_updated_at": null,
      "activation_submitted_at": null,
      "requirements": {
        "disabled_reason": null,
        "errors": [
          {
            "code": "identity_document_verification_failed",
            "message": "The identity document could not be verified.",
            "requirement": "representative.verification.document",
            "resolution": "Ask the account holder to replace the indicated document with a clear, valid and unexpired identity document — a well-lit photo showing the whole document, with readable text — then start a new activation attempt."
          }
        ],
        "missing": [
          "representative.verification.document"
        ],
        "pending_verification": []
      }
    },
    "previous_attributes": {
      "activation_status": "in_review",
      "activation_status_updated_at": "2026-08-11T14:02:00.000Z",
      "activation_submitted_at": "2026-08-11T14:02:00.000Z",
      "requirements": {
        "disabled_reason": null,
        "errors": [],
        "missing": [],
        "pending_verification": [
          "representative.verification.document"
        ]
      }
    }
  },
  "livemode": true,
  "organization": "org_nCotBVzuEaMi3nbW",
  "request": {
    "id": null
  },
  "type": "organization.updated"
}

Exemplo: cadastro aprovado

{
  "id": "evt_nvtgAU9by7ydN2zt",
  "object": "event",
  "created_at": "2026-04-30T18:35:00.000Z",
  "data": {
    "object": {
      "id": "org_nCotBVzuEaMi3nbW",
      "object": "organization",
      "activation_status": "active",
      "activation_status_updated_at": "2026-04-30T18:35:00.000Z",
      "activation_submitted_at": "2026-04-30T18:31:20.000Z",
      "avatar_url": "https://cdn.meusite.com/avatar.png",
      "billing_additional_info": "Recebedor: Financeiro",
      "billing_address": {
        "city": "São Paulo",
        "country": "BR",
        "line1": "Av. Paulista, 1000",
        "line2": null,
        "postal_code": "01310-100",
        "state": "SP"
      },
      "billing_name": "Acme Importadora LTDA",
      "branding_settings": {
        "accent_color": null,
        "border_style": null,
        "brand_color": null,
        "font_family": null,
        "theme": null
      },
      "business_profile": {
        "annual_revenue": {
          "amount": 50000000,
          "currency": "brl"
        },
        "mcc": "5734",
        "url": "https://meusite.com"
      },
      "company": {
        "address": {
          "city": "São Paulo",
          "country": "BR",
          "line1": "Av. Paulista, 1000",
          "line2": null,
          "postal_code": "01310-100",
          "state": "SP"
        },
        "email": "contato@meusite.com",
        "name": "Acme Importadora LTDA",
        "opening_date": "2018-03-10",
        "phone": "+5511999990000",
        "trade_name": "Acme Importadora"
      },
      "created_at": "2026-04-28T13:42:10.000Z",
      "dashboard_settings": {
        "timezone": "America/Sao_Paulo"
      },
      "document": "12345678000190",
      "document_type": "cnpj",
      "email": "contato@meusite.com",
      "individual": null,
      "livemode": true,
      "metadata": {},
      "name": "Acme Importadora",
      "payout_account": {
        "id": "pa_PPiSVpjfXExaQKZ3",
        "object": "payout_account",
        "account_number_last4": "5678",
        "bank_code": "260",
        "bank_name": "Nu Pagamentos S.A.",
        "created_at": "2026-04-30T18:31:20.000Z",
        "holder_name": "Acme Importadora LTDA",
        "is_active": true,
        "is_verified": false,
        "livemode": true,
        "metadata": {},
        "routing_number": "0001",
        "type": "checking",
        "updated_at": "2026-04-30T18:35:00.000Z"
      },
      "platform": "plat_z8wqPdxotjtaBEu8",
      "representative": {
        "address": {
          "city": "São Paulo",
          "country": "BR",
          "line1": "Av. Paulista, 1000",
          "line2": null,
          "postal_code": "01310-100",
          "state": "SP"
        },
        "birthdate": "1988-02-20",
        "document": "98765432100",
        "email": "carlos@meusite.com",
        "first_name": "Carlos",
        "last_name": "Pereira",
        "phone": "+5511988887777"
      },
      "requirements": {
        "disabled_reason": null,
        "errors": [],
        "missing": [],
        "pending_verification": []
      },
      "socials": [
        {
          "platform": "instagram",
          "url": "https://instagram.com/meusite"
        }
      ],
      "statement_descriptor": "ACME IMPORTADORA LTDA",
      "terms_acceptance": {
        "accepted_at": "2026-04-30T18:30:10.000Z",
        "ip": "203.0.113.10",
        "user_agent": "Mozilla/5.0"
      },
      "updated_at": "2026-04-30T18:35:00.000Z",
      "website": "https://meusite.com"
    },
    "previous_attributes": {
      "activation_status": "in_review",
      "requirements": {
        "disabled_reason": null,
        "errors": [],
        "missing": [],
        "pending_verification": [
          "payout_account",
          "representative.verification.document",
          "representative.verification.selfie"
        ]
      }
    }
  },
  "livemode": true,
  "organization": "org_nCotBVzuEaMi3nbW",
  "request": {
    "id": null
  },
  "type": "organization.updated"
}

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

{
  "id": "evt_bbG7e7PbxD4vpKgz",
  "object": "event",
  "created_at": "2026-07-04T12:54:33.000Z",
  "data": {
    "object": {
      "id": "org_nCotBVzuEaMi3nbW",
      "object": "organization",
      "activation_status": "disabled",
      "activation_status_updated_at": "2026-07-04T12:54:33.000Z",
      "activation_submitted_at": "2026-04-30T18:31:20.000Z",
      "avatar_url": "https://cdn.meusite.com/avatar.png",
      "billing_additional_info": "Recebedor: Financeiro",
      "billing_address": {
        "city": "São Paulo",
        "country": "BR",
        "line1": "Av. Paulista, 1000",
        "line2": null,
        "postal_code": "01310-100",
        "state": "SP"
      },
      "billing_name": "Acme Importadora LTDA",
      "branding_settings": {
        "accent_color": null,
        "border_style": null,
        "brand_color": null,
        "font_family": null,
        "theme": null
      },
      "business_profile": {
        "annual_revenue": {
          "amount": 50000000,
          "currency": "brl"
        },
        "mcc": "5734",
        "url": "https://meusite.com"
      },
      "company": {
        "address": {
          "city": "São Paulo",
          "country": "BR",
          "line1": "Av. Paulista, 1000",
          "line2": null,
          "postal_code": "01310-100",
          "state": "SP"
        },
        "email": "contato@meusite.com",
        "name": "Acme Importadora LTDA",
        "opening_date": "2018-03-10",
        "phone": "+5511999990000",
        "trade_name": "Acme Importadora"
      },
      "created_at": "2026-04-28T13:42:10.000Z",
      "dashboard_settings": {
        "timezone": "America/Sao_Paulo"
      },
      "document": "12345678000190",
      "document_type": "cnpj",
      "email": "contato@meusite.com",
      "individual": null,
      "livemode": true,
      "metadata": {},
      "name": "Acme Importadora",
      "payout_account": {
        "id": "pa_PPiSVpjfXExaQKZ3",
        "object": "payout_account",
        "account_number_last4": "5678",
        "bank_code": "260",
        "bank_name": "Nu Pagamentos S.A.",
        "created_at": "2026-04-30T18:31:20.000Z",
        "holder_name": "Acme Importadora LTDA",
        "is_active": true,
        "is_verified": false,
        "livemode": true,
        "metadata": {},
        "routing_number": "0001",
        "type": "checking",
        "updated_at": "2026-04-30T18:35:00.000Z"
      },
      "platform": "plat_z8wqPdxotjtaBEu8",
      "representative": {
        "address": {
          "city": "São Paulo",
          "country": "BR",
          "line1": "Av. Paulista, 1000",
          "line2": null,
          "postal_code": "01310-100",
          "state": "SP"
        },
        "birthdate": "1988-02-20",
        "document": "98765432100",
        "email": "carlos@meusite.com",
        "first_name": "Carlos",
        "last_name": "Pereira",
        "phone": "+5511988887777"
      },
      "requirements": {
        "disabled_reason": null,
        "errors": [
          {
            "code": "identity_name_mismatch",
            "message": "The name provided does not match the name registered for the taxpayer id.",
            "requirement": "representative.verification.document",
            "resolution": "Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt."
          }
        ],
        "missing": [
          "representative.first_name",
          "representative.last_name",
          "representative.verification.document"
        ],
        "pending_verification": []
      },
      "socials": [
        {
          "platform": "instagram",
          "url": "https://instagram.com/meusite"
        }
      ],
      "statement_descriptor": "ACME IMPORTADORA LTDA",
      "terms_acceptance": {
        "accepted_at": "2026-04-30T18:30:10.000Z",
        "ip": "203.0.113.10",
        "user_agent": "Mozilla/5.0"
      },
      "updated_at": "2026-07-04T12:54:33.000Z",
      "website": "https://meusite.com"
    },
    "previous_attributes": {
      "activation_status": "in_review",
      "requirements": {
        "disabled_reason": null,
        "errors": [],
        "missing": [],
        "pending_verification": [
          "representative.verification.document",
          "representative.verification.selfie"
        ]
      }
    }
  },
  "livemode": true,
  "organization": "org_nCotBVzuEaMi3nbW",
  "request": {
    "id": null
  },
  "type": "organization.updated"
}

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:

{
  "id": "evt_oRrDA9rEmesXSYFQ",
  "object": "event",
  "created_at": "2026-07-05T09:12:04.000Z",
  "data": {
    "object": {
      "id": "org_nCotBVzuEaMi3nbW",
      "object": "organization",
      "activation_status": "disabled",
      "activation_status_updated_at": "2026-07-04T12:54:33.000Z",
      "activation_submitted_at": "2026-04-30T18:31:20.000Z",
      "avatar_url": "https://cdn.meusite.com/avatar.png",
      "billing_additional_info": "Recebedor: Financeiro",
      "billing_address": {
        "city": "São Paulo",
        "country": "BR",
        "line1": "Av. Paulista, 1000",
        "line2": null,
        "postal_code": "01310-100",
        "state": "SP"
      },
      "billing_name": "Acme Importadora LTDA",
      "branding_settings": {
        "accent_color": null,
        "border_style": null,
        "brand_color": null,
        "font_family": null,
        "theme": null
      },
      "business_profile": {
        "annual_revenue": {
          "amount": 50000000,
          "currency": "brl"
        },
        "mcc": "5734",
        "url": "https://meusite.com"
      },
      "company": {
        "address": {
          "city": "São Paulo",
          "country": "BR",
          "line1": "Av. Paulista, 1000",
          "line2": null,
          "postal_code": "01310-100",
          "state": "SP"
        },
        "email": "contato@meusite.com",
        "name": "Acme Importadora LTDA",
        "opening_date": "2018-03-10",
        "phone": "+5511999990000",
        "trade_name": "Acme Importadora"
      },
      "created_at": "2026-04-28T13:42:10.000Z",
      "dashboard_settings": {
        "timezone": "America/Sao_Paulo"
      },
      "document": "12345678000190",
      "document_type": "cnpj",
      "email": "contato@meusite.com",
      "individual": null,
      "livemode": true,
      "metadata": {},
      "name": "Acme Importadora",
      "payout_account": {
        "id": "pa_PPiSVpjfXExaQKZ3",
        "object": "payout_account",
        "account_number_last4": "5678",
        "bank_code": "260",
        "bank_name": "Nu Pagamentos S.A.",
        "created_at": "2026-04-30T18:31:20.000Z",
        "holder_name": "Acme Importadora LTDA",
        "is_active": true,
        "is_verified": false,
        "livemode": true,
        "metadata": {},
        "routing_number": "0001",
        "type": "checking",
        "updated_at": "2026-04-30T18:35:00.000Z"
      },
      "platform": "plat_z8wqPdxotjtaBEu8",
      "representative": {
        "address": {
          "city": "São Paulo",
          "country": "BR",
          "line1": "Av. Paulista, 1000",
          "line2": null,
          "postal_code": "01310-100",
          "state": "SP"
        },
        "birthdate": "1988-02-20",
        "document": "98765432100",
        "email": "carlos@meusite.com",
        "first_name": "Carlos",
        "last_name": "Pereira",
        "phone": "+5511988887777"
      },
      "requirements": {
        "disabled_reason": null,
        "errors": [
          {
            "code": "identity_name_mismatch",
            "message": "The name provided does not match the name registered for the taxpayer id.",
            "requirement": "representative.verification.document",
            "resolution": "Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt."
          }
        ],
        "missing": [
          "representative.first_name",
          "representative.last_name",
          "representative.verification.document"
        ],
        "pending_verification": []
      },
      "socials": [
        {
          "platform": "instagram",
          "url": "https://instagram.com/meusite"
        }
      ],
      "statement_descriptor": "ACME IMPORTADORA LTDA",
      "terms_acceptance": {
        "accepted_at": "2026-04-30T18:30:10.000Z",
        "ip": "203.0.113.10",
        "user_agent": "Mozilla/5.0"
      },
      "updated_at": "2026-07-05T09:12:04.000Z",
      "website": "https://meusite.com"
    },
    "previous_attributes": {
      "requirements": {
        "disabled_reason": null,
        "errors": [
          {
            "code": "verification_failed",
            "message": "The financial profile could not be approved.",
            "requirement": "representative",
            "resolution": "Ask the account holder to correct the indicated registration data and start a new activation attempt. If the problem persists, contact support."
          }
        ],
        "missing": [
          "representative"
        ],
        "pending_verification": []
      }
    }
  },
  "livemode": true,
  "organization": "org_nCotBVzuEaMi3nbW",
  "request": {
    "id": null
  },
  "type": "organization.updated"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento organization.updated