Visão geral

Para: Dev · Fin · Adm — Conferido em 2026-10-18.

O Dracma recebe depósitos PIX do seu produto, paga saques PIX dos seus jogadores e avisa cada mudança por webhook. Esta página define os termos que o resto do guia usa e mostra o caminho de ponta a ponta de um depósito e de um saque.

O que é

Seis termos aparecem em todas as páginas.

Termo O que é
Tenant A sua empresa (pessoa jurídica) no Dracma. Agrupa pessoas, operações e a trilha de auditoria. O Dracma cria o tenant; você não se cadastra sozinho.
Operação Uma marca em um país e em um ambiente, por exemplo minhamarca-br-hml e minhamarca-br-prd. É a unidade de credencial, regra, moeda, webhook e saldo. Tudo o que você faz na API pertence a uma operação.
Tipo da operação Teste (simulador, sem dinheiro real, chave key_test_) ou Real (PSP de verdade, dinheiro real, chave key_live_). Veja Ambientes, tipos de operação e hosts.
Conector O serviço do seu lado que fala com o Dracma. Só ele guarda a chave e o segredo, e só ele chama a API.
Jogador O seu usuário final. No Dracma é identificado por player.external_ref: um texto opaco e imutável que nunca é e-mail, telefone ou CPF.
PSP O provedor de pagamento que movimenta o PIX de fato. O Dracma escolhe o PSP de cada operação; o seu conector não conversa com ele.

Duas pessoas também têm nome:

  • Staff do Dracma: quem cria tenants, cadastra e ativa gateways e aprova pedidos de operação Real. Veja Equipe e papéis.
  • Administrador do tenant: a primeira pessoa da sua empresa no painel. Ela entra por convite, vira dona do tenant e convida o resto da equipe.

Tenant e operação vêm só da sua credencial (chave de API e assinatura). O conector nunca informa operation_id para dizer onde está.

Quando usar

Leia esta página antes de qualquer outra. Quem integra a API segue para Do zero ao go-live. Quem opera o dinheiro segue para Modelo de dinheiro. Quem administra a equipe segue para Conta, login e dispositivos.

Como funciona

O que é do Dracma e o que é do seu conector

Responsabilidade Dracma Seu conector
Cobrar o PIX no PSP e confirmar o pagamento sim não
Pagar o saque no PSP, com decisão automática, revisão ou bloqueio sim não
Guardar o saldo do jogador não sim (reserva antes do saque)
Guardar o livro do operador (depósitos pagos, saques, devoluções) sim confere por reconciliação
Avisar mudanças de estado webhook e GET /events recebe, deduplica e confere
Confirmar o estado antes de mover dinheiro expõe GET /deposits/{id} e GET /withdrawals/{id} sempre consulta (fetch-back)
Repetir uma chamada que falhou aceita Idempotency-Key repete com a mesma chave
Bônus, promoções e carteira do jogador fora da API seu produto
Aprovar saque em revisão, mudar regras, gerir equipe painel seu time usa o painel

O seu produto sobe e funciona sem o Dracma. Se o Dracma ficar indisponível, o método PIX fica em fila ou desligado, e o resto da sua operação continua.

Ponta a ponta

sequenceDiagram participant J as Jogador participant C as Seu conector participant D as Dracma (API /v1) participant P as PSP J->>C: quer depositar R$ 50,00 C->>C: grava a intenção (external_id) no seu banco C->>D: POST /v1/deposits (assinado, Idempotency-Key) D-->>C: 201 com instruções PIX C-->>J: mostra o PIX copia e cola J->>P: paga o PIX P->>D: confirma o pagamento (callback) D-->>C: webhook deposit.paid C->>D: GET /v1/deposits/{id} (fetch-back) D-->>C: status paid, valor registrado C->>C: credita o jogador, uma vez, por external_id
sequenceDiagram participant J as Jogador participant C as Seu conector participant D as Dracma (API /v1) participant R as Revisor (painel) participant P as PSP J->>C: pede saque C->>C: reserva o saldo do jogador e grava o external_id C->>D: POST /v1/withdrawals D-->>C: 201 approved (automático) ou under_review opt under_review R->>D: aprova ou recusa no painel end D->>P: envia o PIX P-->>D: confirma D-->>C: webhook withdrawal.paid C->>D: GET /v1/withdrawals/{id} C->>C: finaliza a reserva (ou devolve em rejected, failed, cancelled)

Várias operações por tenant

Um tenant pode ter quantas operações precisar: uma por marca, país e ambiente. Cada operação tem saldo, regras, chaves e webhook próprios, e o painel isola uma da outra: quem tem acesso à operação A não vê a B. Uma chave pertence a uma única operação.

Exemplos

Um tenant com duas marcas no Brasil, com Teste e Real separados:

Operação Tipo Chave Webhook
marca-a-br-hml Teste key_test_… https://pagamentos.marca-a.example/dracma
marca-a-br-prd Real key_live_… https://pagamentos.marca-a.example/dracma
marca-b-br-hml Teste key_test_… https://pagamentos.marca-b.example/dracma

O padrão marca-país-ambiente é só convenção. O nome da operação aceita letras minúsculas, dígitos e hífen.

Erros e casos de borda

  • Chave de Teste em um host de Real (ou o inverso) recebe 401 unknown_key. É a trava que impede apontar o ambiente errado.
  • Mandar operation_id em um corpo de criação não escolhe a operação: o que vale é a chave.
  • Em operação Teste nenhum dinheiro se move. Em operação Real o dinheiro é real, em qualquer instância. Veja o aviso em Ambientes, tipos de operação e hosts.

Veja também