Integre pagamentos Pix com clareza operacional.

Autenticação

Gere uma chave em Dashboard → API Keys. Cada conta cliente pode ter somente uma chave ativa. Para substituí-la, revogue a chave atual e atualize todas as integrações antes de usar a nova.

Authorization: Bearer hp_test_sua_chave
Content-Type: application/json

Também aceitamos X-API-Key. Nunca coloque a chave no frontend, aplicativo móvel ou repositório.

Carteiras

Uma carteira separa saldos e cobranças dentro da mesma conta. Cada cliente pode criar até 50 carteiras, todas acessíveis com a mesma API Key e identificadas por um wallet_id exclusivo.

curl "$HADES_URL/api/v1/wallets" \
  -H "Authorization: Bearer $HADES_API_KEY"

{
  "name": "loja_principal"
}

Criar pagamento Pix

O valor é enviado em reais. Use uma chave de idempotência única por pedido; repetir a chave retorna a mesma cobrança.

curl -X POST "$HADES_URL/api/v1/payments" \
  -H "Authorization: Bearer $HADES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8472-tentativa-1" \
  -d '{
    "wallet_id": "wallet_id_aqui",
    "amount": 100.00,
    "description": "Pedido #8472"
  }'

Resposta

{
  "id": "payment_id",
  "status": "PENDING",
  "paid": false,
  "amount_cents": 10000,
  "fee_cents": 50,
  "net_cents": 9950,
  "pix_copy": "000201...",
  "qr_code": "data:image/png;base64,...",
  "expires_at": "2026-08-12T15:00:00.000Z",
  "paid_at": null
}

A taxa padrão é fixa: R$ 0,50 somente quando o pagamento é confirmado. O administrador pode personalizá-la por cliente.

Certificar pagamento

Consulte o ID retornado na criação. HTTP 200 não significa pagamento: a confirmação exige paid: true junto de status: "PAID".

const response = await fetch(
  process.env.HADES_URL + "/api/v1/payments/" + paymentId,
  { headers: { Authorization: "Bearer " + process.env.HADES_API_KEY } }
);

const payment = await response.json();
if (payment.paid === true && payment.status === "PAID") {
  // Entregue o produto ou confirme o pedido apenas aqui.
}

Transferir entre carteiras

Mova saldo disponível entre dois IDs de carteira pertencentes ao mesmo cliente. O débito e o crédito são atômicos, liquidados imediatamente e não utilizam o provedor Pix.

curl -X POST "$HADES_URL/api/v1/transfers" \
  -H "Authorization: Bearer $HADES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ajuste-operacao-8472" \
  -d '{
    "from_wallet_id": "wallet_origem_id",
    "to_wallet_id": "wallet_destino_id",
    "amount": 250.00,
    "description": "Reforço de caixa"
  }'

Taxa: R$ 0,00. Transferências internas não são pagamentos nem saques reais. A resposta sempre registra fee_cents: 0, e o ledger cria um débito na origem e um crédito no destino.

Escopos necessários: transfers:write no POST e transfers:read no GET. Reutilizar a mesma Idempotency-Key retorna a transferência original sem movimentar o saldo novamente.

Solicitar saque

curl -X POST "$HADES_URL/api/v1/withdrawals" \
  -H "Authorization: Bearer $HADES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: saque-2026-08-12-001" \
  -d '{
    "wallet_id": "wallet_id_aqui",
    "amount": 50.00,
    "pix_key": "cliente@email.com",
    "pix_key_type": "email",
    "fee_mode": "amount"
  }'

fee_mode: "amount" desconta a taxa do valor enviado. fee_mode: "balance" envia o valor integral e debita a taxa à parte.

A taxa padrão é R$ 1,00 por saque concluído. Um novo saque é recusado enquanto houver outro em processamento.

Erros, limites e segurança

{
  "error": "bad_request",
  "message": "Descrição legível do erro"
}

• 400 — payload ou regra financeira inválida
• 401 — chave ausente, inválida ou sem escopo
• 404 — recurso não encontrado
• 409 — limite de 50 carteiras atingido
• 429 — limite de solicitações excedido

Use HTTPS, mantenha a chave somente no backend, gere uma Idempotency-Key por operação e valide sempre o JSON. A Hades Pay credita saldos apenas após confirmação do provedor.