PixUSDT v1

Introdução

O PixUSDT é uma plataforma de pagamentos que recebe PIX em BRL e envia USDT (TRC-20, BEP-20 ou ERC-20) 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

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% + R$0,50 fixo em PIX abaixo de R$50).

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",
    "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.50,
    "total_fee_brl": 2.00,
    "net_brl": 47.90
  },
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_base64": "data:image/png;base64,iVBORw0...",
    "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,
  "total_fees_brl": 374.50,
  "net_brl": 12109.00
}

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.

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-Source: pixusdt

Validação HMAC-SHA256

Sempre valide a assinatura. O PixUSDT assina o body bruto do webhook com o webhook_secret da sua API key. Compare a assinatura recebida no header X-Webhook-Signature com a que você calcula localmente.

Node.js (Express)

javascriptimport crypto from 'node:crypto';
import express from 'express';
const app = express();

const SECRET = process.env.PIXUSDT_WEBHOOK_SECRET; // whsec_...

app.post('/webhook/pixusdt',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.header('X-Webhook-Signature');
    const expected = crypto.createHmac('sha256', SECRET)
      .update(req.body)
      .digest('hex');

    if (sig !== expected) return res.status(401).send('invalid signature');

    const event = JSON.parse(req.body.toString());
    if (event.event === 'pix.received') {
      // marca pedido como pago no seu sistema
      console.log('PIX confirmado:', event.data.charge.id);
    }
    res.status(200).json({ ok: true });
  }
);

PHP (Laravel)

php$secret = env('PIXUSDT_WEBHOOK_SECRET');
$body   = $request->getContent();
$sig    = $request->header('X-Webhook-Signature');
$expected = hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $sig)) {
    abort(401, 'invalid signature');
}

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

Python (FastAPI)

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

SECRET = os.environ['PIXUSDT_WEBHOOK_SECRET'].encode()
app = FastAPI()

@app.post('/webhook/pixusdt')
async def webhook(request: Request):
    body = await request.body()
    sig = request.headers.get('x-webhook-signature', '')
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    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}

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.0 (atual) · Endpoints /v1/charges, /v1/account, /v1/balance. Webhooks pix.received, pix.expired. HMAC-SHA256.