Documentação da API

Criar Pagamento

Cria uma nova cobrança Pix para depósito. O QR Code gerado tem validade de 10 minutos. O valor recebido pode ser convertido automaticamente para as criptomoedas DEPIX, BTC e USDt conforme as taxas abaixo.

Parâmetros do Body:

• value Valor em BRL (Ex: "150.75"). Min R$10(USDt e Depix) e R$20(Bitcoin), Max R$5.000. De acordo com Limites
• email E-mail da conta do cliente que receberá o saldo.
• swap_to opcional Define a moeda de conversão automática. Opções: BTC, USDt, DEPIX.
• euid opcional Identificador do end user (EUID) do pagador. A Depix exige um end user identificado para gerar QR Codes acima de R$10,00. Na 1ª cobrança de um cliente você ainda não tem o EUID — gere-a sem euid e com valor de até R$10,00. Depois do pagamento, o EUID volta no campo payerEuid do get-payment (e do webhook); guarde-o e envie-o no euid das próximas cobranças daquele cliente para liberar valores acima de R$10,00. Veja Como obter o EUID.
• webhook_url opcional URL que receberá notificações quando o pagamento for confirmado.
• webhook_secret opcional Chave secreta para validar a assinatura do webhook (HMAC SHA256).

curl -X POST https://pixbitcoin.org/api/create-payment \
  -H "X-API-Token: <seu_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "250.00",
    "email": "cliente@example.com",
    "swap_to": "BTC",
    "euid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "webhook_url": "https://sua-api.com/webhook",
    "webhook_secret": "seu_secret_seguro"
  }'

{
  "id": "4fbbd7a-c1b1-4f3b-8a3b-18a0b0e5d8d6",
  "qrCopyPaste": "0002012666...",
  "qrImageUrl": "https://api.pixbitcoin.org/qrcodes/4fbb.../image.png",
  "expiresAt": "2025-07-19T16:33:12Z",
  "status": "waiting_payment"
} // headers com X-Webhook-Signature gerado apartir do secret + campos[payment_id, email, value_in_cents, payer_euid]

Consultar Pagamento

Verifica o status de um pagamento específico usando o id retornado na criação.

Status Possíveis:

• waiting_payment: Aguardando o pagamento do Pix.
• pending: Pagamento recebido e aguardando confirmações.
• under_review: Pagamento recebido, mas em análise manual.
• depix_sent: Pagamento confirmado e valor creditado na sua conta.
• canceled: O pagamento foi cancelado pelo sistema ou usuário.
• expired: O tempo para pagamento do QR Code expirou.
• refunded: O valor do pagamento foi devolvido ao pagador.
• after7d: Pagamento de terceiro — saldo convertido mas retido por 7 dias corridos. Saque liberado automaticamente após o prazo.
• error: Ocorreu um erro inesperado no processamento.

curl https://pixbitcoin.org/api/get-payment/4fbb... \
  -H "X-API-Token: <seu_token>"

{
  "qrId": "4fbbd7a-c1b1-4f3b-8a3b-18a0b0e5d8d6",
  "status": "depix_sent",
  "payerName": "Fulano de Tal",
  "payerTaxNumber": "***.456.789-**",
  "payerEuid": "EU013089459847844",  // reutilize no campo "euid" das próximas cobranças deste cliente
  "amount": 25000,
  "updatedAt": "2025-07-19T16:35:02Z"
}

Obter Saldo

Retorna os saldos disponíveis em todas as moedas para a conta associada ao token.

curl https://pixbitcoin.org/api/get-balance \
  -H "X-API-Token: <seu_token>"

{
  "email": "cliente@example.com",
  "balances": {
    "DEPIX": {
      "available_cents": 12345,
      "available_brl": "R$ 123,45"
    },
    "BTC": {
      "available_sats": 987654,
      "available_btc": "0.00987654"
    },
    "USDt": {
      "available_cents_USDt": 2500000,
      "available_USDt": "2.500000"
    }
  }
}

Webhooks

Quando você cria um pagamento com os campos webhook_url e webhook_secret, o sistema enviará automaticamente uma notificação para a URL especificada quando o pagamento for confirmado.

Validação de Assinatura:

Se você fornecer um webhook_secret, o sistema incluirá um header X-Webhook-Signature com a assinatura HMAC SHA256 do payload. Você pode usar isso para validar que a requisição veio realmente do nosso sistema.

Dados Enviados:

• payment_id: ID do pagamento
• email: E-mail do cliente
• value_in_cents: Valor em centavos

{
  "payment_id": "4fbbd7a-c1b1-4f3b-8a3b-18a0b0e5d8d6",
  "email": "cliente@example.com",
  "value_in_cents": 25000
}

import hmac
import hashlib
import json

def validate_webhook(payload, signature, secret):
    message = json.dumps(payload, separators=(',', ':'))
    expected = hmac.new(
        secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)