PixUSDT v1

Introdução

O PixUSDT é uma plataforma de pagamentos que recebe PIX em BRL e envia USDT (TRON / Polygon / BSC) automaticamente para a carteira configurada do lojista. Esta API permite integrar o PixUSDT ao seu checkout, sistema de gestão ou painel administrativo.

Fluxo típico: seu sistema chama POST /v1/charges com o valor → PixUSDT retorna QR code PIX e copia-e-cola → o pagador paga → PixUSDT recebe webhook do PSP, confirma o pagamento, e envia POST assinado para a sua URL configurada → seu sistema marca o pedido como pago.

Autenticação

Todas as requisições à API /v1/* exigem autenticação via API Key. Gere a sua em Dashboard → API Keys & Webhooks. As chaves começam com pk_live_ e devem ser tratadas como senha.

Header padrão (recomendado)

httpAuthorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternativa

httpX-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Health check

Endpoint público pra monitoramento (UptimeRobot, statuspage etc):

json{
  "status": "ok",
  "checks": {
    "database": "ok",
    "psp_mode": "pushinpay"
  },
  "uptime_seconds": 3600,
  "response_time_ms": 2,
  "version": "1.1.0",
  "timestamp": "2026-05-06T12:00:00Z"
}

Retorna HTTP 200 quando tudo OK, 503 se algum serviço crítico está degradado.

Carteira & Rede USDT

O PixUSDT é não-custodial: nós convertemos PIX em USDT e enviamos diretamente para a carteira que você cadastra no painel. Não custodiamos cripto — assim que o PIX é confirmado, o operador da plataforma envia USDT direto pro seu wallet, on-chain, com TX hash registrado e auditável.

Redes suportadas

Cadastre seu endereço e a rede em Dashboard → Meu Perfil → Carteira USDT. O endereço é validado automaticamente conforme o formato da rede escolhida. A consulta da rede atual está disponível em GET /v1/account:

json{
  "id": 42,
  "name": "Loja Exemplo",
  "email": "loja@exemplo.com",
  "role": "admin",
  "usdt_wallet": {
    "address": "TXyz...AbCd",
    "network": "TRON",
    "configured": true
  }
}

Erros

Todas as respostas de erro retornam JSON com a estrutura abaixo. O HTTP status indica a categoria do erro.

json{
  "error": "validation_error",
  "message": "Dados inválidos",
  "details": { ... }
}

Criar cobrança PIX

Gera um QR code PIX que o pagador escaneia / copia-e-cola pra pagar. O valor já vem com taxa da plataforma calculada: 3% sobre o valor do PIX + R$ 0,55 fixo (a taxa fixa é aplicada em todas as cobranças, independente do valor).

Request body

Exemplo cURL

bashcurl -X POST https://pixusdt.org/v1/charges \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "external_id": "pedido-12345",
    "description": "Plano Premium mensal",
    "webhook_url": "https://seu-sistema.com/webhook/pixusdt",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678901"
    }
  }'

Response 201

json{
  "id": "1842",
  "external_id": "pedido-12345",
  "status": "pending",
  "amount": 49.90,
  "amount_cents": 4990,
  "fees": {
    "platform_fee_pct": 3.0,
    "percentage_fee_brl": 1.50,
    "fixed_fee_brl": 0.55,
    "total_fee_brl": 2.05,
    "net_brl": 47.85
  },
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_base64": "data:image/png;base64,iVBORw0...",
    "qr_code_image_url": "data:image/png;base64,iVBORw0...",
    "qr_code_base64_raw": "iVBORw0KGgoAAAANSUhEUgAAA...",
    "copy_paste": "00020126580014BR.GOV.BCB.PIX..."
  },
  "expires_at": "2026-05-05T18:30:00.000Z",
  "created_at": "2026-05-05T18:00:00",
  "psp_id": "a1b5323c-9e68-4afb-8927-94cdcef7a156"
}

Consultar cobrança

Retorna o status atual de uma cobrança. O {id} pode ser tanto o id retornado pelo PixUSDT quanto o external_id que você passou no momento da criação.

bashcurl https://pixusdt.org/v1/charges/pedido-12345 \
  -H "Authorization: Bearer pk_live_xxx"

Status possíveis

Listar cobranças

bashcurl "https://pixusdt.org/v1/charges?status=paid&limit=50" \
  -H "Authorization: Bearer pk_live_xxx"

Info da conta

Retorna informações do dono da API key. Útil pra validar a chave durante setup da integração.

Saldo

json{
  "gross_received_brl": 12483.50,
  "pending_brl": 347.00,
  "sent_usdt_brl": 11250.00,
  "total_fees_brl": 374.50,
  "net_brl": 12109.00,
  "med": {
    "debt_brl": 0,
    "block_threshold_brl": 200,
    "account_blocked": false
  },
  "account_status": "active"
}

Campos

Conversões USDT

Histórico de envios USDT confirmados pelo operador. Cada PIX pago gera uma transaction quando o USDT é enviado on-chain.

bashcurl "https://pixusdt.org/v1/transactions?status=confirmed" \
  -H "Authorization: Bearer pk_live_xxx"

Filtros disponíveis

Response

json{
  "data": [
    {
      "id": "42",
      "charge_id": "1842",
      "external_id": "pedido-12345",
      "amount_brl": 49.90,
      "usdt_amount": 9.18,
      "rate_brl": 5.22,
      "network": "BSC",
      "to_address": "0x95c4d336087276c291bade26b556562be4d52c7b",
      "tx_hash": "0x482cc3...0137",
      "explorer_url": "https://bscscan.com/tx/0x482cc3...0137",
      "network_fee_usd": 0.30,
      "status": "confirmed",
      "sent_at": "2026-05-06T18:23:10Z",
      "confirmed_at": "2026-05-06T18:23:42Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Pra consultar uma conversão específica:

Eventos de Webhook

O PixUSDT envia POST para a URL configurada no dashboard sempre que um evento da sua conta acontece. Cadastre suas URLs em Dashboard → API Keys & Webhooks → Webhooks Configurados.

Exemplo de payload usdt.sent

json{
  "event": "usdt.sent",
  "timestamp": "2026-05-06T18:23:42.521Z",
  "data": {
    "charge": {
      "id": 1842,
      "external_id": "pedido-12345",
      "amount_brl": 49.90,
      "psp_id": "a1b5323c-9e68-4afb-8927-94cdcef7a156"
    },
    "transaction": {
      "id": 42,
      "usdt_amount": 9.18,
      "rate_brl": 5.22,
      "network": "BSC",
      "to_address": "0x95c4d336087276c291bade26b556562be4d52c7b",
      "tx_hash": "0x482cc3...0137",
      "network_fee": 0.30,
      "explorer_url": "https://bscscan.com/tx/0x482cc3...0137",
      "batch": false,
      "status": "sent"
    }
  }
}

Payload do webhook

Todos os webhooks chegam como POST application/json com a estrutura:

json{
  "event": "pix.received",
  "timestamp": "2026-05-05T18:23:14.521Z",
  "data": {
    "charge": {
      "id": 1842,
      "amount_brl": 49.90,
      "status": "paid",
      "paid_at": "2026-05-05 18:23:10",
      "created_at": "2026-05-05 18:00:00",
      "psp_id": "a1b5323c-9e68-4afb-8927-94cdcef7a156",
      "payer_name": "João Silva",
      "payer_document": "123.456.789-01"
    },
    "client": null
  }
}

Headers enviados

httpContent-Type: application/json
X-Webhook-Signature: 4e8c5f3a2b1c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e
X-Webhook-Timestamp: 1714000000
X-Webhook-Id: 9f2d4e8a-1b3c-4d5e-8f9a-1b2c3d4e5f6a
X-Webhook-Source: pixusdt

Validação HMAC-SHA256 + Timestamp (anti-replay)

O PixUSDT assina o webhook em 2 etapas pra prevenir ataques de replay:

• X-Webhook-Timestamp — Unix timestamp (segundos) de quando o webhook foi assinado
• X-Webhook-Signature — HMAC-SHA256 de "{timestamp}.{body_bruto}" usando seu webhook_secret como chave

Sua validação deve fazer 2 checks:

1. O timestamp está dentro de uma janela de tolerância (recomendado: ±5 minutos) — se for fora, rejeita (suspeita de replay)
2. Recalcula HMAC-SHA256 sobre "{timestamp}.{body}" e compara em tempo constante (use hmac.compare_digest, crypto.timingSafeEqual, etc — nunca ===)

Node.js (Express)

javascriptimport crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.PIXUSDT_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SEC = 300; // 5 minutos

const app = express();
app.post('/webhook/pixusdt',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const ts  = req.header('X-Webhook-Timestamp');
    const sig = req.header('X-Webhook-Signature');
    if (!ts || !sig) return res.status(401).send('missing headers');

    // 1) Janela temporal
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - parseInt(ts, 10)) > TOLERANCE_SEC) {
      return res.status(401).send('timestamp out of tolerance');
    }

    // 2) Recalcula HMAC sobre "timestamp.body"
    const expected = crypto.createHmac('sha256', SECRET)
      .update(`${ts}.${req.body.toString()}`)
      .digest('hex');

    // 3) Compara em tempo constante
    const ok = sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
    if (!ok) return res.status(401).send('invalid signature');

    const event = JSON.parse(req.body.toString());
    if (event.event === 'pix.received') {
      console.log('PIX confirmado:', event.data.charge.external_id);
    }
    res.status(200).json({ ok: true });
  }
);

PHP (Laravel)

php$secret    = env('PIXUSDT_WEBHOOK_SECRET');
$tolerance = 300; // 5 minutos

$body = $request->getContent();
$ts   = $request->header('X-Webhook-Timestamp');
$sig  = $request->header('X-Webhook-Signature');

if (!$ts || !$sig) abort(401, 'missing headers');

// 1) Janela temporal
if (abs(time() - intval($ts)) > $tolerance) {
    abort(401, 'timestamp out of tolerance');
}

// 2) Recalcula HMAC sobre "timestamp.body"
$expected = hash_hmac('sha256', $ts . '.' . $body, $secret);

// 3) Compara em tempo constante
if (!hash_equals($expected, $sig)) {
    abort(401, 'invalid signature');
}

$event = json_decode($body, true);
if ($event['event'] === 'pix.received') {
    Order::where('external_id', $event['data']['charge']['external_id'])
         ->update(['status' => 'paid']);
}

Python (FastAPI)

pythonimport hmac, hashlib, os, json, time
from fastapi import FastAPI, Request, HTTPException

SECRET = os.environ['PIXUSDT_WEBHOOK_SECRET'].encode()
TOLERANCE = 300  # 5 minutos
app = FastAPI()

@app.post('/webhook/pixusdt')
async def webhook(request: Request):
    body = await request.body()
    ts   = request.headers.get('x-webhook-timestamp', '')
    sig  = request.headers.get('x-webhook-signature', '')
    if not ts or not sig:
        raise HTTPException(401, 'missing headers')

    # 1) Janela temporal
    if abs(int(time.time()) - int(ts)) > TOLERANCE:
        raise HTTPException(401, 'timestamp out of tolerance')

    # 2) Recalcula HMAC sobre "timestamp.body"
    payload  = f"{ts}.{body.decode()}".encode()
    expected = hmac.new(SECRET, payload, hashlib.sha256).hexdigest()

    # 3) Compara em tempo constante
    if not hmac.compare_digest(sig, expected):
        raise HTTPException(401, 'invalid signature')

    event = json.loads(body)
    if event['event'] == 'pix.received':
        ...  # processa pagamento
    return {'ok': True}

Rotação do Webhook Secret

Quando você regenera sua API key (botão 🔄 REGENERAR no dashboard), o webhook_secret também é trocado. A revogação é imediata — não há grace period no nosso lado:

• O secret antigo é marcado como revoked atomicamente no momento da regeneração
• Webhooks já em voo (disparados antes do clique) podem chegar com a assinatura do secret antigo, dependendo da latência
• Webhooks disparados depois usam o novo secret

Estratégia recomendada do lado cliente pra rotação sem perder webhooks:

1. Configure 2 variáveis de ambiente: PIXUSDT_WEBHOOK_SECRET (atual) e PIXUSDT_WEBHOOK_SECRET_PREV (anterior)
2. No handler do webhook, valide a assinatura contra ambos os secrets — aceita se qualquer um bater
3. Quando rotacionar: pegue o secret novo no dashboard, copie o atual pra _PREV, coloque o novo em _SECRET, faça reload da app
4. Após ~5 minutos (janela de webhooks em voo + retries), pode descartar o _PREV

javascript// Validação aceitando 2 secrets durante janela de rotação
const SECRETS = [
  process.env.PIXUSDT_WEBHOOK_SECRET,
  process.env.PIXUSDT_WEBHOOK_SECRET_PREV
].filter(Boolean);

function isValid(ts, body, sig) {
  return SECRETS.some(secret => {
    const expected = crypto.createHmac('sha256', secret)
      .update(`${ts}.${body}`)
      .digest('hex');
    return sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  });
}

SDKs / Bibliotecas

Atualmente não fornecemos SDKs oficiais — a API é pequena o suficiente pra ser consumida com qualquer client HTTP (axios, requests, Guzzle, etc.). SDKs em Node.js, PHP e Python estão no roadmap.

Changelog

• v1.2 · 2026-05-15
  • Taxa da plataforma simplificada: 3% + R$ 0,55 fixo aplicados em TODAS as cobranças (antes a taxa fixa só caía em PIX abaixo de R$ 50). Campos fees.percentage_fee_brl, fees.fixed_fee_brl e fees.total_fee_brl refletem a nova fórmula.
  • POST /v1/charges: response agora tem 3 campos pra QR Code — pix.qr_code_base64 e pix.qr_code_image_url (string pronta pra <img src=>) + pix.qr_code_base64_raw (base64 puro pra montar manual).
  • Limite por cobrança agora é per-conta (max_charge_brl, default R$ 200). Erro 400 amount_above_limit retorna o limite atual.
  • Gate de perfil: POST /v1/charges exige nome legal + WhatsApp cadastrados — retorna 403 profile_incomplete se incompleto.
  • Erro 403 account_blocked_med: se conta bloqueada por débito de MED, novas cobranças são rejeitadas. Estado consultável via GET /v1/balance.med.
  • Endpoint novo: GET /v1/transactions e GET /v1/transactions/{id} — histórico de envios USDT com tx_hash, network, explorer_url.
  • GET /v1/balance: response expandido com sent_usdt_brl, med.* e account_status.
• v1.1 · 2026-05-06
  • Webhook signature agora inclui X-Webhook-Timestamp (HMAC sobre "{timestamp}.{body}", anti-replay com janela ±5min).
  • Novo evento usdt.sent com TX hash on-chain.
• v1.0 · lançamento
  • Endpoints /v1/charges, /v1/account, /v1/balance.
  • Webhooks pix.received e pix.expired com assinatura HMAC-SHA256.