Catálogo de eventos

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

O Dracma entrega 17 tipos de evento: 9 de depósito e 8 de saque. Esta página lista cada um com o momento em que dispara, o que muda no objeto e o payload completo. O que decide o seu efeito financeiro é sempre o estado devolvido pela consulta à API, não o type do evento.

O que é

O catálogo público é o conjunto de eventos deposit.<estado> e withdrawal.<estado>. O type é o objeto mais o estado alcançado, sem sufixo de versão. Cada evento corresponde a uma transição de estado e leva o objeto completo naquele estado (Envelope).

Evento Quando dispara Em produção hoje
deposit.pending Instruções de pagamento prontas. Primeiro evento do depósito. Sim
deposit.under_review Pagamento recebido e retido para revisão. Sim
deposit.paid Pagamento confirmado. Sim
deposit.expired Prazo de pagamento esgotado. Sim
deposit.cancelled Cancelamento por você, em pending. Sim
deposit.failed Cobrança não criada ou recusada. Sim
deposit.returned Depósito em revisão devolvido: não foi aceito e não é creditado. Sim
deposit.refunded Estorno de depósito pago. Não: só no sandbox
deposit.chargeback Contestação de depósito pago. Não: só no sandbox
withdrawal.under_review Saque retido para revisão manual. Sim
withdrawal.approved Saque aprovado. Sim
withdrawal.processing Pagamento enviado ao PSP, aguardando confirmação. Sim
withdrawal.paid Saque pago. Sim
withdrawal.rejected Saque recusado. Sim
withdrawal.failed Pagamento falhou depois do envio. Sim
withdrawal.cancelled Saque cancelado antes do envio. Sim
withdrawal.returned Valor devolvido pelo banco depois do paid. Sim

Não disponível

deposit.refunded e deposit.chargeback fazem parte do catálogo e já podem ser assinados, mas em produção o Dracma não os emite hoje: eles só ocorrem no sandbox, pelas ações refund e chargeback. Implemente o tratamento agora, porque o seu código precisa sobreviver a eles; não conte com eles para conciliar dinheiro em produção.

Quando usar

Use o catálogo para:

Como funciona

O primeiro evento de cada objeto

  • Depósito: o primeiro evento é deposit.pending, com object_version 2. Não existe deposit.created: a criação responde pela própria chamada POST /v1/deposits.
  • Saque: não existe evento público withdrawal.requested. O primeiro evento é o de decisão (withdrawal.under_review ou withdrawal.approved, e, se as regras recusam de imediato, withdrawal.rejected).

Transições que geram evento

stateDiagram-v2 [*] --> pending [*] --> failed pending --> paid pending --> under_review pending --> expired pending --> cancelled pending --> failed under_review --> paid under_review --> returned paid --> refunded paid --> chargeback
stateDiagram-v2 [*] --> under_review [*] --> approved [*] --> rejected [*] --> cancelled under_review --> approved under_review --> rejected under_review --> cancelled approved --> processing approved --> cancelled processing --> paid processing --> failed paid --> returned

O que fazer em cada evento

O que manda é sempre o estado devolvido pela consulta à API, não o type do evento. O type só diz qual objeto consultar. Os eventos podem chegar fora de ordem e podem ser forjados; veja Receptor passo a passo.

Depósitos (detalhes em Ciclo do depósito):

Evento Estado na consulta Ação do operador
deposit.pending pending Nenhum dinheiro se move. Exiba o QR Code ou o copia-e-cola ao jogador.
deposit.under_review under_review Nenhum dinheiro se move. Os motivos estão em review_reasons. Avise o jogador de que o pagamento está em análise.
deposit.paid paid Credita o jogador pelo valor que você registrou na criação, uma única vez.
deposit.expired, deposit.cancelled, deposit.failed idem Terminal. Nenhum crédito.
deposit.returned returned Terminal. Nenhum crédito.
deposit.refunded, deposit.chargeback idem Débito de um depósito já creditado. A política é sua. Recomendação: não debite automaticamente; abra uma decisão manual e dispare um alerta.

Saques (detalhes em Ciclo do saque). Você reservou (debitou) o valor antes de chamar POST /v1/withdrawals:

Evento Estado na consulta Ação do operador
withdrawal.under_review, withdrawal.approved, withdrawal.processing idem Nenhum dinheiro se move. A reserva continua.
withdrawal.paid paid Finaliza: a reserva vira saída definitiva. psp_reference identifica o pagamento.
withdrawal.rejected, withdrawal.failed, withdrawal.cancelled idem Devolve a reserva ao jogador, uma única vez.
withdrawal.returned returned O banco devolveu o valor depois do paid, e o dinheiro voltou ao caixa da operação. A política é sua. Recomendação: não recredite o jogador automaticamente; abra uma decisão manual e dispare um alerta.

Eventos reservados e tipos futuros

Não disponível

rules.updated aparece em listas antigas de eventos, mas nunca é entregue e não pode ser assinado: o Dracma não emite esse evento. Para saber se as regras mudaram, consulte GET /v1/rules quando precisar.

Reservado no contrato

O contrato reserva tipos de versões mais novas, que pertencem a métodos ainda não disponíveis (transferência bancária, SWIFT, cripto, cartão) ou a regras desligadas: deposit.pending_compliance, deposit.frozen, deposit.paid_partial, withdrawal.pending_compliance, withdrawal.sent, withdrawal.in_transit, withdrawal.recall_requested, withdrawal.recall_rejected, withdrawal.recalled e receipt.unmatched, receipt.matched, receipt.returned, receipt.frozen. Nenhum deles tem gatilho hoje.

O seu código precisa sobreviver a eles mesmo assim: o catálogo só cresce.

  • type desconhecido ou status desconhecido na consulta: responda 200, grave o id do evento para a deduplicação, não credite, não debite e não devolva a reserva, e trate o objeto como não terminal. Confirme de novo depois, pela consulta e por GET /events.
  • Campo desconhecido no JSON: ignore. Nunca falhe a leitura por causa dele.
  • Dinheiro só se move em estado que você conhece e cuja regra está escrita no seu código.

Exemplos

Cada bloco abaixo é o corpo completo de um webhook (formatado para leitura; o corpo real é compacto). Os dados são fictícios e consistentes entre os blocos: o mesmo depósito percorre os estados de depósito e o mesmo saque percorre os de saque, exceto nos desfechos alternativos (por exemplo, deposit.expired e deposit.paid são desfechos excludentes do mesmo pending). Os campos de saque que o contrato reserva para versões futuras (rail, fees, fx e semelhantes) vêm sempre null ou vazios.

deposit.pending

O depósito foi aceito e as instruções de pagamento estão prontas. É o primeiro evento de um depósito (não existe deposit.created).

  • instructions.pix.copy_paste traz o código copia-e-cola do PIX e instructions.pix.expires_at o limite para pagar.
  • paid_amount, payer e paid_at ainda são null; review_reasons é [].
  • version é 2.
{
  "id": "evt_686599cbb91280cbb34334f16f643047",
  "type": "deposit.pending",
  "created_at": "2026-10-18T14:00:02Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
  "object_version": 2,
  "data": {
    "object": {
      "id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
      "external_id": "pedido-10482",
      "status": "pending",
      "version": 2,
      "amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "paid_amount": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "payer": null,
      "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:00:02Z",
      "paid_at": null,
      "expires_at": "2026-10-18T14:30:00Z"
    }
  }
}

deposit.under_review

O pagamento chegou, mas ficou retido para revisão por um ou mais motivos em review_reasons (por exemplo PAYER_MISMATCH, AMOUNT_MISMATCH, PAID_AFTER_EXPIRY; a lista é aberta).

  • paid_amount, payer e paid_at já estão preenchidos; payer.matches_player mostra se o pagador é o jogador.
  • O depósito ainda não creditou ninguém. O desfecho vem em deposit.paid ou deposit.returned, depois da decisão de revisão no painel.
{
  "id": "evt_2b71e0124e8cbbe5451debd56cbc66b7",
  "type": "deposit.under_review",
  "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": "under_review",
      "version": 3,
      "amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "paid_amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "method": "pix",
      "player_ref": "jogador-7731",
      "payer": {
        "document": {
          "type": "CPF",
          "number": "98765432100",
          "country": "BR"
        },
        "name": "Joao Exemplo",
        "matches_player": false
      },
      "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": [
        "PAYER_MISMATCH"
      ],
      "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"
    }
  }
}

deposit.paid

O pagamento foi confirmado e liberado. É o único estado de depósito que credita o jogador.

  • paid_amount, payer e paid_at estão preenchidos.
  • Também é o evento do depósito que estava em revisão e foi aceito na revisão do painel.
{
  "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"
    }
  }
}

deposit.expired

O prazo de pagamento passou sem pagamento. Estado terminal.

  • paid_amount, payer e paid_at seguem null; as instructions continuam no objeto, mas não valem mais.
{
  "id": "evt_778446c795b6d20f8acb5355a32a953e",
  "type": "deposit.expired",
  "created_at": "2026-10-18T14:30:05Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
  "object_version": 3,
  "data": {
    "object": {
      "id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
      "external_id": "pedido-10482",
      "status": "expired",
      "version": 3,
      "amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "paid_amount": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "payer": null,
      "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:30:05Z",
      "paid_at": null,
      "expires_at": "2026-10-18T14:30:00Z"
    }
  }
}

deposit.cancelled

O depósito foi cancelado por POST /v1/deposits/{id}/cancel enquanto estava pending. Estado terminal.

  • O cancelamento só é aceito em pending.
{
  "id": "evt_838f541b2f29b73a96d98632accec428",
  "type": "deposit.cancelled",
  "created_at": "2026-10-18T14:10:00Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
  "object_version": 3,
  "data": {
    "object": {
      "id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
      "external_id": "pedido-10482",
      "status": "cancelled",
      "version": 3,
      "amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "paid_amount": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "payer": null,
      "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:10:00Z",
      "paid_at": null,
      "expires_at": "2026-10-18T14:30:00Z"
    }
  }
}

deposit.failed

A cobrança não foi criada ou foi recusada. Estado terminal.

  • failure_code traz o motivo como texto; trate-o como opaco.
  • Quando a falha acontece antes de o depósito ficar pending, instructions é null e a version é 2.
{
  "id": "evt_7ea95f4af5ebdcc1371cfc51e86f7f4f",
  "type": "deposit.failed",
  "created_at": "2026-10-18T14:00:02Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
  "object_version": 2,
  "data": {
    "object": {
      "id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
      "external_id": "pedido-10482",
      "status": "failed",
      "version": 2,
      "amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "paid_amount": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "payer": null,
      "instructions": null,
      "failure_code": "psp_rejected",
      "review_reasons": [],
      "created_at": "2026-10-18T14:00:00Z",
      "updated_at": "2026-10-18T14:00:02Z",
      "paid_at": null,
      "expires_at": "2026-10-18T14:30:00Z"
    }
  }
}

deposit.returned

O depósito estava em revisão e foi devolvido (não aceito). Estado terminal; o jogador não é creditado.

  • review_reasons mantém os motivos que levaram à revisão.
{
  "id": "evt_ecc47d81a80f12aaef9d7f3dbbacafc6",
  "type": "deposit.returned",
  "created_at": "2026-10-18T16:20:00Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
  "object_version": 4,
  "data": {
    "object": {
      "id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
      "external_id": "pedido-10482",
      "status": "returned",
      "version": 4,
      "amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "paid_amount": {
        "amount": "10000",
        "currency": "BRL"
      },
      "method": "pix",
      "player_ref": "jogador-7731",
      "payer": {
        "document": {
          "type": "CPF",
          "number": "98765432100",
          "country": "BR"
        },
        "name": "Joao Exemplo",
        "matches_player": false
      },
      "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": [
        "PAYER_MISMATCH"
      ],
      "created_at": "2026-10-18T14:00:00Z",
      "updated_at": "2026-10-18T16:20:00Z",
      "paid_at": "2026-10-18T14:05:12Z",
      "expires_at": "2026-10-18T14:30:00Z"
    }
  }
}

deposit.refunded

Um depósito já paid foi estornado. Estado terminal.

  • Em produção este evento não é emitido hoje; ele só ocorre no sandbox, pela ação refund.
{
  "id": "evt_8650c7d795cd73a5699cfb0aa9f620c2",
  "type": "deposit.refunded",
  "created_at": "2026-10-18T18:00:00Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
  "object_version": 4,
  "data": {
    "object": {
      "id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
      "external_id": "pedido-10482",
      "status": "refunded",
      "version": 4,
      "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-18T18:00:00Z",
      "paid_at": "2026-10-18T14:05:12Z",
      "expires_at": "2026-10-18T14:30:00Z"
    }
  }
}

deposit.chargeback

Um depósito já paid sofreu contestação (chargeback/MED). Estado terminal.

  • Em produção este evento não é emitido hoje; ele só ocorre no sandbox, pela ação chargeback.
{
  "id": "evt_bd9b8dee7775b625eb1708bc52e2d8c4",
  "type": "deposit.chargeback",
  "created_at": "2026-10-18T19:00:00Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
  "object_version": 4,
  "data": {
    "object": {
      "id": "dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d",
      "external_id": "pedido-10482",
      "status": "chargeback",
      "version": 4,
      "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-18T19:00:00Z",
      "paid_at": "2026-10-18T14:05:12Z",
      "expires_at": "2026-10-18T14:30:00Z"
    }
  }
}

withdrawal.under_review

O saque ficou retido para revisão manual. decision.mode é manual e decision.reasons traz os códigos da regra que exigiu revisão.

  • Ainda não há decided_by nem decided_at. O desfecho vem em withdrawal.approved, withdrawal.rejected ou withdrawal.cancelled.
{
  "id": "evt_29ad1449656a8e1d6e85c8984ea98109",
  "type": "withdrawal.under_review",
  "created_at": "2026-10-18T15:00:01Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
  "object_version": 2,
  "data": {
    "object": {
      "id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
      "external_id": "saque-55120",
      "status": "under_review",
      "version": 2,
      "amount": {
        "amount": "25000",
        "currency": "BRL"
      },
      "fee": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "decision": {
        "mode": "manual",
        "reasons": [
          "FIRST_WITHDRAWAL"
        ],
        "ruleset_version": 3,
        "decided_by": [],
        "decided_at": null
      },
      "psp_reference": null,
      "failure_code": null,
      "created_at": "2026-10-18T15:00:00.482913Z",
      "updated_at": "2026-10-18T15:00:01.482913Z",
      "paid_at": null,
      "rail": null,
      "fees": [],
      "charge_bearer": null,
      "fx": null,
      "purpose": null,
      "compliance": null,
      "expected_settlement_date": null,
      "sent_at": null,
      "tracking": null,
      "return": null,
      "recall": null
    }
  }
}

withdrawal.approved

O saque foi aprovado (automaticamente ou depois da revisão) e segue para pagamento.

  • Neste exemplo a aprovação foi automática: decision.mode é automatic e decision.reasons é []. Depois de uma revisão, mode é manual e decided_by lista os revisores (ids opacos).
{
  "id": "evt_3985aee553b478cd940b64cd894b5c9c",
  "type": "withdrawal.approved",
  "created_at": "2026-10-18T15:00:01Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
  "object_version": 2,
  "data": {
    "object": {
      "id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
      "external_id": "saque-55120",
      "status": "approved",
      "version": 2,
      "amount": {
        "amount": "25000",
        "currency": "BRL"
      },
      "fee": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "decision": {
        "mode": "automatic",
        "reasons": [],
        "ruleset_version": 3,
        "decided_by": [],
        "decided_at": "2026-10-18T15:00:01.482913Z"
      },
      "psp_reference": null,
      "failure_code": null,
      "created_at": "2026-10-18T15:00:00.482913Z",
      "updated_at": "2026-10-18T15:00:01.482913Z",
      "paid_at": null,
      "rail": null,
      "fees": [],
      "charge_bearer": null,
      "fx": null,
      "purpose": null,
      "compliance": null,
      "expected_settlement_date": null,
      "sent_at": null,
      "tracking": null,
      "return": null,
      "recall": null
    }
  }
}

withdrawal.processing

O pagamento foi enviado ao PSP e aguarda a confirmação. Esse estado pode durar.

  • Nenhum dinheiro se move no seu livro: a reserva continua.
{
  "id": "evt_0a55546ba2d5971d5d2b40b53d8e41a5",
  "type": "withdrawal.processing",
  "created_at": "2026-10-18T15:00:05Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
  "object_version": 3,
  "data": {
    "object": {
      "id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
      "external_id": "saque-55120",
      "status": "processing",
      "version": 3,
      "amount": {
        "amount": "25000",
        "currency": "BRL"
      },
      "fee": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "decision": {
        "mode": "automatic",
        "reasons": [],
        "ruleset_version": 3,
        "decided_by": [],
        "decided_at": "2026-10-18T15:00:01.482913Z"
      },
      "psp_reference": null,
      "failure_code": null,
      "created_at": "2026-10-18T15:00:00.482913Z",
      "updated_at": "2026-10-18T15:00:05.482913Z",
      "paid_at": null,
      "rail": null,
      "fees": [],
      "charge_bearer": null,
      "fx": null,
      "purpose": null,
      "compliance": null,
      "expected_settlement_date": null,
      "sent_at": null,
      "tracking": null,
      "return": null,
      "recall": null
    }
  }
}

withdrawal.paid

O saque foi pago.

  • psp_reference traz o identificador do pagamento no PSP (o E2E do PIX, quando informado) e paid_at o instante do pagamento.
{
  "id": "evt_f7530e95349e7188505699cbb57808c7",
  "type": "withdrawal.paid",
  "created_at": "2026-10-18T15:00:09Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
  "object_version": 4,
  "data": {
    "object": {
      "id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
      "external_id": "saque-55120",
      "status": "paid",
      "version": 4,
      "amount": {
        "amount": "25000",
        "currency": "BRL"
      },
      "fee": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "decision": {
        "mode": "automatic",
        "reasons": [],
        "ruleset_version": 3,
        "decided_by": [],
        "decided_at": "2026-10-18T15:00:01.482913Z"
      },
      "psp_reference": "E00000000202610181500a1b2c3d4e5f",
      "failure_code": null,
      "created_at": "2026-10-18T15:00:00.482913Z",
      "updated_at": "2026-10-18T15:00:09.482913Z",
      "paid_at": "2026-10-18T15:00:09.482913Z",
      "rail": null,
      "fees": [],
      "charge_bearer": null,
      "fx": null,
      "purpose": null,
      "compliance": null,
      "expected_settlement_date": null,
      "sent_at": null,
      "tracking": null,
      "return": null,
      "recall": null
    }
  }
}

withdrawal.rejected

O saque foi recusado pelas regras ou pela revisão. Estado terminal; a reserva volta ao jogador.

  • Neste exemplo a recusa foi manual: decision.mode é manual e decided_by lista o revisor.
{
  "id": "evt_ddfeaba5f991ca15e30c0acab6a3320c",
  "type": "withdrawal.rejected",
  "created_at": "2026-10-18T15:20:00Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
  "object_version": 3,
  "data": {
    "object": {
      "id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
      "external_id": "saque-55120",
      "status": "rejected",
      "version": 3,
      "amount": {
        "amount": "25000",
        "currency": "BRL"
      },
      "fee": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "decision": {
        "mode": "manual",
        "reasons": [
          "FIRST_WITHDRAWAL"
        ],
        "ruleset_version": 3,
        "decided_by": [
          "0198b7c1-9d2e-7a40-b1c2-3d4e5f607182"
        ],
        "decided_at": "2026-10-18T15:20:00.482913Z"
      },
      "psp_reference": null,
      "failure_code": null,
      "created_at": "2026-10-18T15:00:00.482913Z",
      "updated_at": "2026-10-18T15:20:00.482913Z",
      "paid_at": null,
      "rail": null,
      "fees": [],
      "charge_bearer": null,
      "fx": null,
      "purpose": null,
      "compliance": null,
      "expected_settlement_date": null,
      "sent_at": null,
      "tracking": null,
      "return": null,
      "recall": null
    }
  }
}

withdrawal.failed

O pagamento falhou depois do envio ao PSP. Estado terminal; a reserva volta ao jogador.

  • failure_code traz o motivo como texto; trate-o como opaco.
{
  "id": "evt_e789a50d09bedcb67ac6efbb41b4be81",
  "type": "withdrawal.failed",
  "created_at": "2026-10-18T15:00:09Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
  "object_version": 4,
  "data": {
    "object": {
      "id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
      "external_id": "saque-55120",
      "status": "failed",
      "version": 4,
      "amount": {
        "amount": "25000",
        "currency": "BRL"
      },
      "fee": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "decision": {
        "mode": "automatic",
        "reasons": [],
        "ruleset_version": 3,
        "decided_by": [],
        "decided_at": "2026-10-18T15:00:01.482913Z"
      },
      "psp_reference": null,
      "failure_code": "psp_failed",
      "created_at": "2026-10-18T15:00:00.482913Z",
      "updated_at": "2026-10-18T15:00:09.482913Z",
      "paid_at": null,
      "rail": null,
      "fees": [],
      "charge_bearer": null,
      "fx": null,
      "purpose": null,
      "compliance": null,
      "expected_settlement_date": null,
      "sent_at": null,
      "tracking": null,
      "return": null,
      "recall": null
    }
  }
}

withdrawal.cancelled

O saque foi cancelado antes de ser enviado ao PSP (por POST /v1/withdrawals/{id}/cancel ou automaticamente, por exemplo quando o jogador entra numa lista de bloqueio antes do envio). Estado terminal; a reserva volta ao jogador.

  • O cancelamento só é aceito antes de processing.
{
  "id": "evt_5378edae6b397dfb7406e4a94e1bb93e",
  "type": "withdrawal.cancelled",
  "created_at": "2026-10-18T15:10:00Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
  "object_version": 3,
  "data": {
    "object": {
      "id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
      "external_id": "saque-55120",
      "status": "cancelled",
      "version": 3,
      "amount": {
        "amount": "25000",
        "currency": "BRL"
      },
      "fee": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "decision": {
        "mode": "manual",
        "reasons": [
          "FIRST_WITHDRAWAL"
        ],
        "ruleset_version": 3,
        "decided_by": [],
        "decided_at": null
      },
      "psp_reference": null,
      "failure_code": null,
      "created_at": "2026-10-18T15:00:00.482913Z",
      "updated_at": "2026-10-18T15:10:00.482913Z",
      "paid_at": null,
      "rail": null,
      "fees": [],
      "charge_bearer": null,
      "fx": null,
      "purpose": null,
      "compliance": null,
      "expected_settlement_date": null,
      "sent_at": null,
      "tracking": null,
      "return": null,
      "recall": null
    }
  }
}

withdrawal.returned

O banco devolveu o valor depois de o saque estar paid. Estado terminal.

  • return traz reason_code (código curto informado na devolução), returned_amount e returned_at.
{
  "id": "evt_930eb572efc340d1aa4b69f117dc41e2",
  "type": "withdrawal.returned",
  "created_at": "2026-10-19T09:30:00Z",
  "operation_id": "0198b7c2-3d4e-7f50-8a61-92b3c4d5e6f7",
  "object_id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
  "object_version": 5,
  "data": {
    "object": {
      "id": "wdr_0198b7c3a1b27c4d8e5f60718293a4b5",
      "external_id": "saque-55120",
      "status": "returned",
      "version": 5,
      "amount": {
        "amount": "25000",
        "currency": "BRL"
      },
      "fee": null,
      "method": "pix",
      "player_ref": "jogador-7731",
      "decision": {
        "mode": "automatic",
        "reasons": [],
        "ruleset_version": 3,
        "decided_by": [],
        "decided_at": "2026-10-18T15:00:01.482913Z"
      },
      "psp_reference": "E00000000202610181500a1b2c3d4e5f",
      "failure_code": null,
      "created_at": "2026-10-18T15:00:00.482913Z",
      "updated_at": "2026-10-19T09:30:00.482913Z",
      "paid_at": "2026-10-18T15:00:09.482913Z",
      "rail": null,
      "fees": [],
      "charge_bearer": null,
      "fx": null,
      "purpose": null,
      "compliance": null,
      "expected_settlement_date": null,
      "sent_at": null,
      "tracking": null,
      "return": {
        "reason_code": "MD06",
        "returned_amount": {
          "amount": "25000",
          "currency": "BRL"
        },
        "returned_at": "2026-10-19T09:30:00.482913Z"
      },
      "recall": null
    }
  }
}

Erros e casos de borda

  • Evento não assinado: se a sua assinatura de eventos não inclui o tipo, o Dracma não envia aquele webhook (a entrega fica skipped), mas o evento continua disponível em GET /events. Quem assina só deposit.paid não vê deposit.under_review nem deposit.expired por webhook. O seu job de recuperação precisa tratar todos os tipos. Veja Recuperação com GET /events.
  • Transições rápidas: cada transição gera o seu próprio webhook; o Dracma não junta transições. Mesmo assim, eventos distintos podem chegar em qualquer ordem, e o data.object de cada um é o estado daquela transição. Você pode ver deposit.paid antes de deposit.pending. Aplique pelo estado da consulta e por object_version.
  • Pagamento depois da expiração: se o dinheiro chegar depois de o depósito já estar expired, no código atual o depósito continua expired e não há novo evento; o Dracma sinaliza o caso internamente para tratamento. Se o seu jogador diz que pagou, consulte o depósito e abra um chamado com o id do depósito. Veja Problemas comuns.
  • withdrawal.returned em produção: o evento ocorre quando o banco devolve um saque já pago, e return.reason_code traz o código curto informado na devolução. No sandbox, a ação return simula o mesmo evento com um código de simulação.
  • Estados internos: estados que não estão nesta lista (como o requested do saque) não geram webhook.
  • Lista que cresce: o catálogo é aditivo. Um tipo novo é sempre opcional para você tratar, e um tipo desconhecido nunca é motivo para responder erro.

Veja também