PSPs¶

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

O PSP é quem move o PIX de verdade. O Dracma escolhe o PSP de cada operação e de cada direção (depósito ou saque); você não escolhe PSP por chamada. Esta página mostra quais PSPs existem, em que tipo de operação cada um roda, o que isso muda para o seu conector e o que o Dracma nunca faz.

O que é¶

Regras fixas separam os ambientes:

• Uma operação Teste usa sempre o simulador. Nenhum PSP real é chamado e nenhum dinheiro se move. O simulador é recusado em operação Real.
• Uma operação Real usa PSP real e move dinheiro real, em qualquer instância (hml ou prd). Os PSPs reais são recusados em operação Teste.
• Na instância de produção (prd) o simulador não existe: todas as operações são Reais.
• Na instância de homologação (hml), o PSP real só é usado numa operação Real que o Dracma habilitou para isso. Sem a habilitação, uma operação Real em hml não tem por onde mover dinheiro: o depósito falha e o saque fica approved.

O Mercado Pago não tem API pública de pagamento PIX para chave de terceiros. Por isso ele só atende depósitos. Uma operação que usa Mercado Pago para depositar precisa de outro PSP para sacar (hoje, a MaximaxPay).

Quando usar¶

Leia esta página:

• no onboarding, para saber qual PSP a sua operação usa em cada direção e o que ele exige do seu conector;
• ao ver muitos depósitos em under_review com PAYER_UNKNOWN;
• ao ver saques parados em approved por falta de PSP de saque.

Como funciona¶

Quem escolhe o PSP¶

O Dracma guarda, por operação, uma lista de conexões de PSP, cada uma com direção (cash_in, cash_out ou ambas) e prioridade. O cadastro é feito pelo time do Dracma; o operador vê o resultado em Painel: gateways.

• A escolha é fixa por tentativa. O depósito fica no PSP escolhido na criação da cobrança. O saque usa o PSP escolhido na criação da tentativa.
• Não há failover de saque. O Dracma nunca troca o PSP de um saque no meio do caminho nem manda o mesmo pedido a dois PSPs: isso poderia pagar duas vezes. Se o PSP de saque ficar indisponível, os saques esperam (veja Ciclo do saque).
• A queda de um PSP não derruba a operação. A API do Dracma continua no ar. O depósito afetado vai a failed (psp_unavailable); o saque afetado espera.

O que cada PSP muda para o seu conector¶

Consequências práticas:

• Mercado Pago: planeje equipe de revisão para os depósitos em PAYER_UNKNOWN, ou aceite que eles demorem. GET /v1/currencies avisa isso com a nota payer_identity_unavailable em method_details.
• Sempre mande player.name e player.email do cadastro do jogador (lido do seu servidor), mesmo que a operação use MaximaxPay. Fora de produção, o e-mail precisa ser de um domínio reservado (.test, .invalid, .example).
• Saque com MaximaxPay: sempre mande o IP do jogador em player.ip. Sem ele, o saque nunca sai no automático.
• A confirmação do pagamento chega ao Dracma por uma notificação assinada do PSP, mas ela só dispara uma conferência: o Dracma consulta o PSP antes de levar o depósito a paid ou o saque a paid. Notificação sem assinatura válida é descartada sem efeito.
• Valide com valores mínimos. Em operação Real, a primeira transação de depósito e de saque deve ser de valor mínimo e acompanhada dos dois lados (veja Checklist de go-live).

O caixa é seu, mesmo com conta compartilhada¶

O PSP pode guardar o dinheiro de várias operações em uma mesma conta, ou dar uma conta própria à sua operação. Isso é escolha do Dracma e o operador não vê a diferença. Em qualquer dos casos, o caixa da sua operação é separado: GET /v1/balances mostra apenas a sua posição, calculada pelo livro do Dracma, e os saques da sua operação só consomem o seu caixa. Nunca existe saldo "da conta do PSP" visível na API (veja Saldos e caixa livre).

O que você não controla¶

• Qual PSP atende a sua operação e em que ordem.
• As credenciais do PSP. Elas ficam sob guarda do Dracma e não passam pelo seu conector.
• A configuração das notificações do PSP. O endereço de callback do PSP é do Dracma e é diferente do seu webhook.
• O prazo e as regras próprias de cada PSP.

Exemplos¶

Exigências de uma operação Real que usa Mercado Pago para depósitos, como o conector as lê em GET /v1/currencies:

{
  "data": [
    {
      "code": "BRL",
      "kind": "fiat",
      "exponent": 2,
      "methods": ["pix"],
      "method_details": [
        {
          "method": "pix",
          "deposit_requirements": ["player.name", "player.email"],
          "psp_notes": ["payer_identity_unavailable"]
        }
      ]
    }
  ]
}

Erros e casos de borda¶

Veja também¶

• Modelo de dinheiro
• Ciclo do depósito
• Ciclo do saque
• Tarifas
• Painel: gateways
• Ambientes, tipos de operação e hosts
• Referência: ping e moedas