Cobrança em cripto e links de pagamento¶

Para: Dev — Conferido em 2026-11-14.

Esta página descreve como cobrar em BRL e receber em cripto pela API (method: "crypto" em POST /v1/deposits), como mostrar ao jogador quanto ele paga antes de cobrar (GET /v1/fx/quote) e como criar um link de pagamento público (/v1/payment-links). Autenticação, Idempotency-Key, erros problem+json, paginação e webhooks são os mesmos do restante da API; aqui está só o que muda.

O que é¶

A cobrança continua em BRL; o jogador a quita no ativo escolhido (BTC.BTC, USDT.TRON e os demais de Cripto). A operação recebe o ativo, não BRL. O Dracma trava a cotação na criação, reserva um endereço único para a cobrança e devolve tudo o que o jogador precisa para pagar.

Cripto vem desligada e é habilitada por operação. Com ela desligada, ou com o ativo fora da lista da operação, as rotas respondem 403 crypto_not_enabled. GET /v1/currencies mostra o que a sua operação aceita.

Quando usar¶

• Cobrança direta (POST /v1/deposits): o seu produto já sabe o valor e o ativo e mostra o QR ao jogador, ou o leva ao checkout_url.
• Cotação antes de cobrar (GET /v1/fx/quote): para exibir "R$ 100,00 = 0,00021053 BTC" na tela de escolha. Não reserva nada.
• Link de pagamento: você precisa de uma URL para mandar por mensagem ou e-mail e deixar o pagador escolher o método. O link não é uma cobrança: a cobrança nasce quando o pagador age na página pública.

Como funciona¶

Cotar: GET /v1/fx/quote¶

A resposta (CotacaoCripto) traz amount, pay_currency, pay_amount (unidade mínima do ativo), pay_amount_decimal, rate, mid_rate, spread_bps, quoted_at, expires_at e binding: false. Pontos que costumam enganar:

• binding: false quer dizer que nada foi travado. O valor travado só nasce no POST /v1/deposits (ou na ação do pagador num link) e pode ser diferente do que a cotação mostrou.
• rate é BRL por 1 unidade maior do ativo (1 BTC), já com o spread. Não é a taxa inversa do câmbio de carteiras (POST /v1/fx/quotes, outra rota, outra semântica).
• spread_bps é o da configuração da operação. Mandar spread_bps na query é ignorado.
• Dinheiro é sempre texto, nunca número JSON. pay_amount_decimal é decimal exato, sem arredondamento de ponto flutuante.
• A rota tem limite próprio de 60 por minuto por operação e responde Cache-Control: no-store.

Criar a cobrança: POST /v1/deposits com method: "crypto"¶

O corpo é o mesmo de Depósitos, com estas regras a mais:

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" }
  },
  "amount": { "amount": "10000", "currency": "BRL" },
  "method": "crypto",
  "method_options": { "crypto": { "pay_currency": "BTC.BTC" } }
}

O 201 traz status: "pending" e instructions.crypto (InstrucoesCripto):

{
  "id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a6b",
  "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "pending",
  "version": 2,
  "amount": { "amount": "10000", "currency": "BRL" },
  "method": "crypto",
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "provider": "chain",
  "instructions": {
    "crypto": {
      "address": "tb1qexemplo0000000000000000000000000000",
      "network": "bitcoin",
      "pay_currency": "BTC.BTC",
      "pay_amount": { "amount": "21053", "currency": "BTC.BTC" },
      "pay_amount_decimal": "0.00021053",
      "rate": "475000.00",
      "mid_rate": "500000.00",
      "spread_bps": 500,
      "quoted_at": "2026-11-14T12:00:00Z",
      "expires_at": "2026-11-14T12:15:00Z",
      "payment_uri": "bitcoin:tb1qexemplo0000000000000000000000000000?amount=0.00021053",
      "checkout_url": "https://pay.example.test/c/chk_exemploexemploexemploexemploexemploexe",
      "confirmations_required": 3,
      "testnet": true
    }
  },
  "crypto": null,
  "created_at": "2026-11-14T12:00:00Z",
  "updated_at": "2026-11-14T12:00:01Z",
  "expires_at": "2026-11-14T12:15:00Z"
}

• Replay: a mesma Idempotency-Key devolve as mesmas instruções (mesmo endereço, mesma cotação, mesmo expires_at), nunca uma cotação nova.
• 202: a cadeia ainda está reservando o endereço. status vem created e instructions vem null. Espere deposit.pending ou consulte o depósito; não crie outro.
• 503 quote_unavailable: a cotação ou a rede está fora (Retry-After, reason em sources_diverge, stale, insufficient_sources, upstream_down, invalid_rate ou store_unavailable). Nada foi criado. Repita com a mesma Idempotency-Key.

Estados da cobrança em cripto¶

Só paid credita. detected e confirming nunca movem dinheiro, nem no seu livro. Vale o instante em que o recibo foi visto, não o da confirmação: pagar dentro do prazo e confirmar depois do expires_at ainda resulta em paid.

under_review vem com crypto.review_reason e o equivalente em maiúsculas em review_reasons:

A revisão é resolvida no painel pelo Dracma. Não credite o jogador enquanto o estado for under_review.

Reorganização da rede. Antes de paid, a cobrança volta a pending sem crédito. Depois de paid, o Dracma emite deposit.chargeback: desfaça o crédito do seu lado quando o fetch-back mostrar chargeback.

O objeto crypto (progresso)¶

Preenchido só em method: "crypto", e null até haver recibo.

O seu livro de jogador continua em BRL: ao ver paid no fetch-back, credite o jogador por amount (BRL), como em PIX. credited e spread_amount descrevem o que o Dracma credita à operação em ativo; não os use para creditar o jogador.

Webhooks¶

Assinados e entregues como os demais (veja Webhooks): at-least-once, com fetch-back obrigatório.

O receptor deve tratar tipo desconhecido com 200 e sem mover dinheiro. Para payment_link.paid, o last_charge_id aponta a cobrança: confira GET /v1/payment-links/{id} e GET /v1/deposits/{id} antes de creditar.

Links de pagamento¶

Um link é uma URL pública, https://pay.<domínio>/l/<slug>, que deixa o pagador escolher o método. O url devolvido pela API já vem completo. O slug (128 bits) é a capacidade pública e é diferente do id (plk_...); usar o slug no lugar do id nas rotas da API responde 404.

Corpo de POST /v1/payment-links (CriarLink; campo desconhecido é 400):

{
  "external_id": "link-2026-11-0001",
  "player": {
    "external_ref": "0192a3b4-0000-7000-8000-000000000001",
    "document": { "type": "CPF", "number": "12345678909", "country": "BR" }
  },
  "amount_type": "fixed",
  "amount": { "amount": "10000", "currency": "BRL" },
  "allowed_methods": [
    { "method": "pix" },
    { "method": "crypto", "assets": ["BTC.BTC", "USDT.TRON"] }
  ],
  "usage": "single",
  "description": "Recarga de saldo",
  "expires_at": "2026-11-21T12:00:00Z"
}

Resposta 201 (LinkDePagamento):

{
  "id": "plk_01J9ZQ3EXEMPLO",
  "external_id": "link-2026-11-0001",
  "status": "active",
  "version": 1,
  "usage": "single",
  "amount_type": "fixed",
  "amount": { "amount": "10000", "currency": "BRL" },
  "min_amount": null,
  "max_amount": null,
  "allowed_methods": [
    { "method": "pix" },
    { "method": "crypto", "assets": ["BTC.BTC", "USDT.TRON"] }
  ],
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "description": "Recarga de saldo",
  "url": "https://pay.example.test/l/Abcdefghijklmnopqrstuv",
  "max_uses": null,
  "uses_paid": 0,
  "last_charge_id": null,
  "expires_at": "2026-11-21T12:00:00Z",
  "paid_at": null,
  "cancelled_at": null,
  "metadata": {},
  "created_at": "2026-11-14T12:00:00Z",
  "updated_at": "2026-11-14T12:00:00Z"
}

• Em single existe no máximo uma cobrança não terminal por vez.
• Cancelar (POST /v1/payment-links/{id}/cancel, Idempotency-Key obrigatória): active passa a cancelled. Cobranças do link ainda pending, sem pagamento detectado, são canceladas junto. Uma cobrança com pagamento detected ou confirming segue até o fim, porque o dinheiro já está a caminho; se ficar paid num link single, o link vira paid. Link paid ou expired responde 409 invalid_state_transition. Repetir o cancelamento de um link cancelled devolve 200 com o mesmo corpo.
• Listar (GET /v1/payment-links): filtros external_id, status e player_ref, mais cursor e limit (1 a 200; fora disso 400). Só aparecem links da sua operação.

O que o pagador vê na página pública¶

A página pay é só front: o servidor dela fala com a API por assinatura entre serviços, e nenhum segredo vai ao navegador. Ela mostra o valor em BRL, o ativo, a rede, o endereço, o valor exato a enviar, o QR, a cotação, a contagem regressiva e o estado, e se atualiza sozinha. Ela não mostra nem devolve: identificadores internos (dep_, plk_), o seu external_id, o jogador e o documento, metadata, o spread, a cotação sem spread, tarifas nem o nome do provedor.

• Um token ou slug desconhecido, malformado ou de outro ambiente responde 404 idêntico: não há como descobrir quais existem.
• Link paid, expired ou cancelled aberto na rota pública responde 410 payment_link_unavailable.
• O estado visível ao pagador segue os da tabela acima, em texto simples (por exemplo "Aguardando pagamento", "Confirmando", "Pagamento confirmado", "Pagamento em análise"). O pagamento só vale quando o seu fetch-back lê paid.
• Fora de produção o checkout mostra um aviso de rede de testes.

Erros¶

Em POST /v1/deposits com cripto, a ordem de avaliação é: autenticação e escopo, validação do corpo, crypto_not_enabled, asset_not_supported, amount_out_of_range, regras, cotação (quote_unavailable) e endereço. O primeiro que falha decide a resposta. Os códigos estão no formato problem+json de Erros.

Erros comuns¶

Veja também¶

• Depósitos, o fluxo comum a PIX e cripto.
• Cripto e Links de pagamento, a visão de quem opera e de quem paga.
• Catálogo de eventos e Idempotência.