Depósitos¶

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

Um depósito é uma intenção de cobrança PIX: você o cria, o Dracma devolve o copia-e-cola, o jogador paga e o Dracma avisa por webhook. Esta página descreve as quatro rotas (criar, consultar, listar e cancelar), a validação do corpo, os erros na ordem em que a API os confere e os campos que o objeto Deposito realmente devolve.

O que é¶

Hoje só existe PIX em BRL. Qualquer outro método do enum Metodo responde 400 method_not_enabled.

O Dracma credita o valor cheio no depósito pago. O objeto Deposito não traz tarifa descontada: o campo fee do contrato não é devolvido (veja a seção "Objeto Deposito" mais abaixo). As tarifas do contrato com o Dracma estão em Tarifas.

Quando usar¶

O fluxo recomendado, de ponta a ponta:

1. Grave o depósito no seu lado antes de chamar o Dracma.
2. Chame POST /v1/deposits com Idempotency-Key igual ao external_id. Use timeout de cliente de 10 s.
3. Em erro de rede, 5xx ou 429, repita com a mesma chave. Se perdeu a resposta, consulte GET /v1/deposits?external_id=.
4. Mostre instructions.pix.copy_paste ao jogador até instructions.pix.expires_at.
5. Ao receber deposit.paid, verifique a assinatura, deduplique e faça o fetch-back com GET /v1/deposits/{id}. Só credite quando o status lido for paid.

Nunca credite pelo corpo do webhook. O efeito de cada estado no seu livro está em Ciclo do depósito.

Como funciona¶

Criar: POST /v1/deposits¶

O corpo é um objeto JSON com estas chaves. Qualquer chave fora da lista é recusada.

Para PIX o documento do jogador só pode ser CPF ou CNPJ. Os outros tipos passam na validação de forma, mas voltam 422 document_invalid.

O documento do jogador fica fixado no primeiro uso do external_ref. Mandar outro documento para o mesmo external_ref depois resulta em 422 document_mismatch. Veja Dados e privacidade.

Validação estrita. O corpo é recusado com 400 validation_failed, antes de qualquer efeito, quando tem:

operation_id na raiz do corpo é descartado em silêncio: o tenant e a operação vêm só da credencial. Não o envie. method_options e fx_quote_id existem só no contrato 1.1.0 (o documento OpenAPI servido não os traz) e não são aceitos em depósito PIX: voltam unknown_field (veja Divergências conhecidas). Corpo acima de 64 KiB volta 413.

Exigências por operação¶

Alguns PSPs exigem dados que o contrato deixa opcionais. O Dracma escolhe o PSP de depósito de cada operação no onboarding e declara as exigências em GET /v1/currencies (method_details[].deposit_requirements). Veja Ping e moedas.

Quando a operação exige um campo e ele vem ausente, em branco ou só com espaços, a API recusa antes de criar qualquer coisa e antes do motor de regras:

• É um 4xx: não cria objeto, jogador nem evento. A mesma Idempotency-Key devolve o mesmo 400 por 30 dias. Depois de corrigir o cadastro, crie com external_id novo.
• Mande o e-mail cadastrado do jogador, lido do seu servidor. Nunca um e-mail digitado no pedido de depósito e nunca um inventado.
• Em operação Teste, e-mail real de um cadastro copiado de produção recebe reserved_domain_required. Reescreva os e-mails do seu ambiente de teste (por exemplo jogador1@operador.test). Se a operação não exige e-mail, não envie o campo.
• Mande sempre player.name: operações reais costumam exigi-lo.
• Em operação Real o domínio do e-mail não é restrito, só o formato.

Resposta 201: PIX pronto¶

O depósito é criado e o PSP já devolveu o PIX. status vem pending, version vem 2 e instructions.pix traz copy_paste (o BR Code, que é o conteúdo do QR) e expires_at. qr_code_png_base64 vem quando o PSP o fornece; se não vier, gere o QR a partir do copy_paste.

• Use o instructions.pix.expires_at devolvido, não o prazo que você pediu: o PSP pode ajustar o prazo.
• Em operação Teste o BR Code é sintético e nenhum dinheiro real se move.
• 201 com status: "failed" também existe: o PSP recusou a cobrança antes da resposta. O objeto foi criado e é conclusivo (veja failure_code). Não repita; crie outro depósito com external_id novo se fizer sentido.

Resposta 202: aceito, PIX ainda não disponível¶

Se o PSP demorar mais que o orçamento de resposta da API (cerca de 7 s), o Dracma responde 202 com status: "created", version: 1 e instructions: null. Não é erro. Espere o webhook deposit.pending ou consulte GET /v1/deposits/{id} até o status ser pending, e então mostre o PIX. Não crie outro depósito para tentar de novo.

Consultar: GET /v1/deposits/{id}¶

É o fetch-back: o estado autoritativo que você lê antes de creditar. 200 devolve o Deposito. Um id que não existe nesta operação responde 404 not_found. Objeto de outra operação também é 404, nunca 403, e um id fora do formato dep_ seguido de letras e números também.

Antes de creditar, confira o que veio contra o que você gravou na criação: external_id, amount.amount, amount.currency e player_ref têm de ser idênticos. Se algo divergir, não credite, marque para revisão e alerte.

Listar: GET /v1/deposits¶

Escopo read. Usa o balde de listagem do rate limit (veja Limites e quotas).

A resposta é {"data": [Deposito, ...], "next_cursor": "dep_..." | null}. A ordem é a do id do depósito, que segue a ordem de criação, e não a de updated_at. next_cursor é o id dep_... do último item da página e vira null na última. Para uma varredura incremental, guarde o maior updated_at visto e use updated_since com ele (o >= repete o último item, então deduplique). Veja Paginação e filtros.

Assine o caminho com a query exatamente como enviada.

Cancelar: POST /v1/deposits/{id}/cancel¶

Escopo deposits:write. Corpo vazio. Idempotency-Key obrigatória.

• Só cancela de pending. A resposta é 200 com o objeto em cancelled. Se ele já estava cancelled, a resposta é o mesmo 200, sem evento novo.
• Em created, paid, expired, under_review ou qualquer outro estado, a resposta é 409 invalid_state_transition. Em created, espere pending e cancele depois.
• Cancelar no Dracma não cancela a cobrança no PSP. O PIX continua pagável até o prazo do PSP. Se alguém pagar depois, o estado não muda e o paid_amount é gravado: não credite e trate como exceção. Veja Política de exceções de dinheiro e a divergência D-D2 em Divergências conhecidas.

Expiração¶

O Dracma expira sozinho o depósito pending depois de expires_at mais 2 minutos de folga (o job roda a cada 30 s). A folga existe porque o PSP ainda pode aceitar o pagamento logo depois do prazo. Ao expirar sai o webhook deposit.expired.

Objeto Deposito¶

O Deposito é o mesmo no 201, no GET e no data.object do webhook. A API devolve 16 campos e nenhum outro. Os campos da v1.1.0 do contrato (rail, received_amount, receipts, fee, fees, fx, compliance, expected_settlement_date, return) existem no contrato 1.1.0, mas não no documento OpenAPI servido, e nunca são devolvidos em depósito. Não dependa deles.

payer. Traz document (type, number, country), name e matches_player, que é true quando o documento de quem pagou bate com o do jogador. Use-o só para exibir e auditar; a decisão de crédito é o status.

status. O enum StatusDeposito tem 13 valores:

Estado desconhecido é não-terminal e não move dinheiro no seu lado: confira de novo pelo fetch-back (leitor tolerante). A máquina de estados completa e o efeito de cada estado no seu livro estão em Ciclo do depósito.

review_reasons. Lista aberta de códigos em maiúsculas, por exemplo PAYER_MISMATCH, PAYER_UNKNOWN, AMOUNT_MISMATCH, PAID_AFTER_EXPIRY, RULES_UNAVAILABLE e RULES_INVALID_RESPONSE. Código desconhecido não muda nada: o que manda é o status. O significado de cada um e o que o painel faz com ele está em Ciclo do depósito.

Exemplos¶

Pedido de criação (os valores de assinatura são ilustrativos; o algoritmo está em Autenticação HMAC):

POST /v1/deposits HTTP/1.1
Host: api.example.test
Content-Type: application/json; charset=utf-8
Idempotency-Key: dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b
Dracma-Key-Id: key_test_01J9EXEMPLO
Dracma-Timestamp: 1790000000
Dracma-Nonce: 0123456789abcdef0123456789abcdef
Dracma-Signature: v1=<assinatura>

{
  "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "player": {
    "external_ref": "0192a3b4-0000-7000-8000-000000000001",
    "document": { "type": "CPF", "number": "12345678909", "country": "BR" },
    "name": "Jogador Teste",
    "email": "jogador1@operador.test",
    "ip": "203.0.113.10"
  },
  "amount": { "amount": "5000", "currency": "BRL" },
  "method": "pix",
  "expires_in_seconds": 1800
}

Resposta 201, PIX pronto:

{
  "id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a6b",
  "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "pending",
  "version": 2,
  "amount": { "amount": "5000", "currency": "BRL" },
  "paid_amount": null,
  "method": "pix",
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "payer": null,
  "instructions": {
    "pix": {
      "copy_paste": "00020126...6304ABCD",
      "expires_at": "2026-10-18T15:30:00Z"
    }
  },
  "failure_code": null,
  "review_reasons": [],
  "created_at": "2026-10-18T15:00:00Z",
  "updated_at": "2026-10-18T15:00:01Z",
  "paid_at": null,
  "expires_at": "2026-10-18T15:30:00Z"
}

Resposta 202, PIX ainda não disponível:

{
  "id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a6c",
  "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c",
  "status": "created",
  "version": 1,
  "amount": { "amount": "5000", "currency": "BRL" },
  "paid_amount": null,
  "method": "pix",
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "payer": null,
  "instructions": null,
  "failure_code": null,
  "review_reasons": [],
  "created_at": "2026-10-18T15:00:00Z",
  "updated_at": "2026-10-18T15:00:00Z",
  "paid_at": null,
  "expires_at": "2026-10-18T15:30:00Z"
}

O mesmo depósito depois de pago, lido no fetch-back:

{
  "id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a6b",
  "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "paid",
  "version": 3,
  "amount": { "amount": "5000", "currency": "BRL" },
  "paid_amount": { "amount": "5000", "currency": "BRL" },
  "method": "pix",
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "payer": {
    "document": { "type": "CPF", "number": "12345678909", "country": "BR" },
    "name": "Jogador Teste",
    "matches_player": true
  },
  "instructions": {
    "pix": {
      "copy_paste": "00020126...6304ABCD",
      "expires_at": "2026-10-18T15:30:00Z"
    }
  },
  "failure_code": null,
  "review_reasons": [],
  "created_at": "2026-10-18T15:00:00Z",
  "updated_at": "2026-10-18T15:07:41Z",
  "paid_at": "2026-10-18T15:07:40Z",
  "expires_at": "2026-10-18T15:30:00Z"
}

Um depósito em revisão porque o pagador não é o jogador. Não credite:

{
  "id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a6d",
  "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6d",
  "status": "under_review",
  "version": 3,
  "amount": { "amount": "5000", "currency": "BRL" },
  "paid_amount": { "amount": "5000", "currency": "BRL" },
  "method": "pix",
  "player_ref": "0192a3b4-0000-7000-8000-000000000002",
  "payer": {
    "document": { "type": "CPF", "number": "98765432100", "country": "BR" },
    "name": "Outra Pessoa",
    "matches_player": false
  },
  "instructions": {
    "pix": {
      "copy_paste": "00020126...6304ABCD",
      "expires_at": "2026-10-18T15:30:00Z"
    }
  },
  "failure_code": null,
  "review_reasons": ["PAYER_MISMATCH"],
  "created_at": "2026-10-18T15:00:00Z",
  "updated_at": "2026-10-18T15:09:10Z",
  "paid_at": "2026-10-18T15:09:09Z",
  "expires_at": "2026-10-18T15:30:00Z"
}

Recusa por exigência da operação (400, sem objeto criado):

{
  "type": "https://docs.dracma.test/errors/validation_failed",
  "title": "validation_failed",
  "status": 400,
  "code": "validation_failed",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "retryable": false,
  "errors": [
    {
      "field": "player.email",
      "message": "obrigatório nesta operação (exigência do PSP de cash-in; ver GET /v1/currencies)",
      "reason": "required_by_operation"
    }
  ]
}

Listagem para achar um depósito pelo seu id:

GET /v1/deposits?external_id=dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b&limit=10 HTTP/1.1

Erros e casos de borda¶

Erros da criação, na ordem em que a API os confere¶

Notas:

• document_invalid no passo 9 cobre CPF ou CNPJ com dígito verificador errado. velocity_exceeded no depósito cobre muitos depósitos criados e não pagos numa janela. Os limiares são da regra da operação: consulte Regras (API) e Decisão, limites e regras.
• Recusa 4xx não cria objeto. A mesma Idempotency-Key devolve a mesma recusa, guardada por 30 dias. Se você usa Idempotency-Key = external_id, tentar de novo depois de uma recusa exige external_id novo. Veja Idempotência e repetição.
• Erro de rede, timeout, 5xx e 429 não são respostas conclusivas: repita com a mesma chave.

Erros das outras rotas¶

Casos de borda¶

• Pagamento depois de expirar ou cancelar. Se o PIX é pago com o depósito já em expired, cancelled ou failed, o estado não muda: o Dracma grava paid_amount, paid_at e o pagador e alerta. Para você, paid_amount preenchido num estado sem crédito é exceção: não credite. Veja Ciclo do depósito.
• under_review não credita. O dinheiro entrou, mas há divergência. Espere o desfecho (paid ou returned).
• Estado e evento novos. Aplique o leitor tolerante: campo, estado ou motivo desconhecido nunca devem derrubar o seu parser nem mover dinheiro.
• Ambiente. Em operação Teste, e-mail com domínio real é recusado (reserved_domain_required) e nenhum dinheiro se move.

Veja também¶

• Ciclo do depósito: estados, efeito no seu livro e pagamento tardio.
• Ping e moedas: deposit_requirements.
• Erros e Idempotência e repetição
• Webhooks e Catálogo de eventos
• Sandbox: como simular pagamento, expiração, estorno e chargeback.
• Objetos e campos