Envelope

Para: Dev — Conferido em 2026-10-18.

Todo webhook e todo item de GET /events têm o mesmo envelope: sete campos de topo e o objeto completo (depósito ou saque) em data.object. Esta página define cada campo, o formato dos ids e a relação entre object_version e version.

O que é

O envelope é o objeto Evento da referência da API. O Dracma serializa o corpo em JSON compacto, com os campos de topo sempre na ordem abaixo. Não dependa da ordem nem da formatação: leia o JSON por nome de campo e ignore campos que você não conhece.

Campo Tipo Nulo? Exemplo Descrição
id string nunca evt_5a9c1f0e7b3d4c28a6e1f4b07d92c385 Id do evento: evt_ seguido de 32 caracteres hexadecimais minúsculos. É igual ao header Dracma-Event-Id e é a chave de deduplicação. Um evento mantém o mesmo id em todas as tentativas e reentregas.
type string nunca deposit.paid Tipo do evento: <objeto>.<estado alcançado>, sem sufixo de versão. Lista em Catálogo de eventos.
created_at string nunca 2026-10-18T14:05:13Z Instante em que a transição aconteceu, em RFC 3339, sempre em UTC com Z e sem frações de segundo no webhook.
operation_id string nunca 0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7 UUID da sua operação, em minúsculas. Um evento só chega à URL da operação a que pertence.
object_id string nunca dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d Id do objeto: dep_ (depósito) ou wdr_ (saque) seguido de 32 hexadecimais. É igual a data.object.id.
object_version inteiro nunca 3 Versão do objeto na transição, maior ou igual a 1. É igual a data.object.version.
data.object objeto nunca veja abaixo O depósito ou o saque completo, como estava no momento da transição.

Todos os campos são obrigatórios e nenhum deles vem nulo. Os ids evt_, dep_ e wdr_ são opacos: trate-os como texto, sem interpretar o conteúdo.

Quando usar

Use esta página para modelar o parser do seu receptor e a tabela de eventos já processados:

  • Deduplicação: guarde id (igual a Dracma-Event-Id) por no mínimo 7 dias.
  • Fetch-back: use object_id para consultar GET /v1/deposits/{object_id} ou GET /v1/withdrawals/{object_id}. O tipo de objeto vem do prefixo do type (deposit. ou withdrawal.).
  • Ordenação: compare object_version com a última versão aplicada para o mesmo object_id.

Como funciona

data.object

O data.object é o mesmo objeto que a API devolve nas consultas: o Deposito em eventos deposit.* e o Saque em eventos withdrawal.*, com o status igual ao estado anunciado no type. Ele traz o objeto inteiro, não só o id e o status, e fica congelado no estado da transição: uma reentrega feita horas depois leva o objeto daquele momento, não o atual. Por isso o seu receptor nunca credita pelo corpo do webhook e sempre confirma o estado atual com uma consulta autenticada.

Campos que mudam com o estado, por tipo de objeto:

Objeto Campos que variam por estado
Depósito status, version, instructions (preenchido a partir de deposit.pending), paid_amount, payer e paid_at (preenchidos em deposit.paid e deposit.under_review), review_reasons (preenchido em deposit.under_review), failure_code (preenchido em deposit.failed), expires_at, updated_at.
Saque status, version, decision (mode, reasons, decided_by, decided_at), psp_reference (preenchido em withdrawal.paid), failure_code (preenchido em withdrawal.failed), paid_at, return (preenchido em withdrawal.returned), updated_at.

O payload completo de cada evento está em Catálogo de eventos. As definições campo a campo estão em Objetos e campos.

object_version e version

object_version (no envelope) e version (dentro de data.object) são o mesmo contador: sobe em 1 a cada transição do objeto. Se o envelope diz "object_version": 3, o objeto traz "version": 3. O contador só cresce, então ele ordena os eventos de um mesmo objeto mesmo quando a entrega chega fora de ordem: ignore um evento cuja versão seja menor ou igual à última que você aplicou.

O primeiro evento de um depósito é deposit.pending, com versão 2 (o estado interno inicial não vira evento). O primeiro evento visível de um saque depende da decisão: pode ser withdrawal.under_review ou withdrawal.approved, também com versão 2. As versões que você vê podem não ser contíguas: o estado inicial de um saque (requested), por exemplo, não gera evento público.

Formato dos instantes

  • No envelope, created_at do webhook tem precisão de segundos (2026-10-18T14:05:13Z).
  • Dentro de data.object, os instantes do depósito têm precisão de segundos. Os do saque podem trazer frações de segundo (por exemplo 2026-10-18T15:00:09.482913Z).
  • Em GET /events, o created_at do envelope de um saque também pode trazer frações.

Faça o parse de RFC 3339 com e sem frações. Valores monetários vêm como objeto { "amount": "<inteiro em string>", "currency": "BRL" }, com o valor inteiro na menor unidade da moeda.

Exemplos

Um evento deposit.paid completo, como chega ao seu receptor (formatado aqui para leitura; o corpo real é compacto). Os dados são fictícios.

{
  "id": "evt_e12d177892007213962d29c4b3b60580",
  "type": "deposit.paid",
  "created_at": "2026-10-18T14:05:13Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
  "object_version": 3,
  "data": {
    "object": {
      "id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
      "external_id": "pedido-10482",
      "status": "paid",
      "version": 3,
      "amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "paid_amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "method": "pix",
      "player_ref": "jogador-7731",
      "payer": {
        "document": {
          "type": "CPF",
          "number": "12345678909",
          "country": "BR"
        },
        "name": "Maria Exemplo",
        "matches_player": true
      },
      "instructions": {
        "pix": {
          "copy_paste": "00020126580014br.gov.bcb.pix0136exemplo-chave-ficticia5204000053039865406100.005802BR5909EXEMPLO6009SAO PAULO62070503***6304ABCD",
          "expires_at": "2026-10-18T14:30:00Z"
        }
      },
      "failure_code": null,
      "review_reasons": [],
      "created_at": "2026-10-18T14:00:00Z",
      "updated_at": "2026-10-18T14:05:13Z",
      "paid_at": "2026-10-18T14:05:12Z",
      "expires_at": "2026-10-18T14:30:00Z"
    }
  }
}

Repare que object_id repete data.object.id e que object_version repete data.object.version.

Erros e casos de borda

  • Campo desconhecido: ignore. O Dracma só acrescenta campos; nunca falhe a leitura por causa de um.
  • type desconhecido: responda 200, grave o id para a deduplicação e não mova dinheiro. Veja Receptor passo a passo.
  • status desconhecido em data.object: trate o objeto como não terminal e confirme depois.
  • Id curto nos exemplos antigos: a referência da API e os vetores de assinatura usam ids curtos como evt_01J9ZQ5. É só um exemplo; o formato real tem 32 caracteres hexadecimais depois do prefixo. Não valide o comprimento de forma rígida: use apenas o prefixo e o conjunto de caracteres.
  • operation_id no vetor de teste: o valor op_nero_hml dos vetores é fictício e não tem o formato de UUID da operação real.
  • Objeto fora de ordem: um evento com object_version menor que o já aplicado não é erro; responda 200 sem efeito.

Veja também