LiquiBR v1

Introdução

O LiquiBR é 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 LiquiBR ao seu checkout, sistema de gestão ou painel administrativo.

Fluxo típico: seu sistema chama POST /v1/charges com o valor → LiquiBR retorna QR code PIX e copia-e-cola → o pagador paga → LiquiBR 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 LiquiBR é 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": "[email protected]",
  "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

Headers opcionais

Idempotência

Tanto external_id (body) quanto Idempotency-Key (header) servem como chave de idempotência. Comportamento:

• Mesma chave + mesmo amount nas últimas 24h: retorna a charge existente com HTTP 200 (não 201), header Idempotent-Replay: true, e campo idempotent_replay: true no body. Não cobra duas vezes.
• Mesma chave + amount diferente nas últimas 24h: retorna HTTP 409 idempotency_conflict. Use outra chave ou aguarde 24h.
• Sem chave: sempre cria nova charge (sem proteção contra duplicação).

Exemplo cURL

bashcurl -X POST https://liquibr.com/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/liquibr",
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "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 LiquiBR quanto o external_id que você passou no momento da criação.

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

Status possíveis

Listar cobranças

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

Filtros disponíveis

Cancelar cobrança

Cancela explicitamente uma charge ainda em pending antes que ela expire sozinha. Útil quando o pedido foi cancelado no seu sistema. A charge passa pra status refunded.

bashcurl -X DELETE https://liquibr.com/v1/charges/pedido-12345 \
  -H "Authorization: Bearer pk_live_xxx"

json{
  "id": "1842",
  "status": "refunded",
  "cancelled_at": "2026-05-30T18:23:14Z"
}

Estorno de cobrança paga (não implementado)

Endpoint reservado pra estorno de charges com status paid. Atualmente retorna 501 not_implemented — o endpoint existe pra você não precisar refatorar o cliente quando for liberado.

json{
  "error": "not_implemented",
  "message": "Estornos via API ainda não estão disponíveis. Solicite via suporte.",
  "support": {
    "email": "[email protected]",
    "ticket_url": "https://liquibr.com/support"
  },
  "charge_reference": "1842",
  "estimated_response_time": "2 horas úteis"
}

Pra estornar uma charge paga hoje, abra ticket em /support com o charge_reference. Atendimento médio de 2 horas úteis.

Webhook de teste

Dispara um payload de teste pra sua webhook_url, com assinatura HMAC válida. Use durante setup pra validar sua integração antes de criar charges reais.

bashcurl -X POST https://liquibr.com/v1/webhooks/test \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://seu-sistema.com/webhook/liquibr",
    "event_type": "pix.received"
  }'

json{
  "ok": true,
  "status_code": 200,
  "duration_ms": 142,
  "error": null,
  "signature_sent": "4e8c5f3a2b1c9d8e7f6a...",
  "timestamp_sent": "1717092194",
  "payload_sent": { ... }
}

O payload simulado tem a mesma estrutura do evento real (com dados fictícios). Sua integração processa exatamente como faria com um evento de produção — perfeito pra validar HMAC, timeout e idempotência.

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://liquibr.com/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 LiquiBR 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 LiquiBR 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.LIQUIBR_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SEC = 300; // 5 minutos

const app = express();
app.post('/webhook/liquibr',
  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('LIQUIBR_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['LIQUIBR_WEBHOOK_SECRET'].encode()
TOLERANCE = 300  # 5 minutos
app = FastAPI()

@app.post('/webhook/liquibr')
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}

Auditoria de disparos

Pra debugar webhooks que falharam ou consultar o histórico de entregas:

Retorna as últimas tentativas (até 3 por evento), incluindo body enviado, status code retornado pelo seu servidor, latência, erro de rede (se houver) e os primeiros 4KB da resposta.

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: LIQUIBR_WEBHOOK_SECRET (atual) e LIQUIBR_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.LIQUIBR_WEBHOOK_SECRET,
  process.env.LIQUIBR_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));
  });
}

Fluxo de integração CRM (end-to-end)

Esse é o fluxo típico pra integrar um CRM/sistema de gestão de pedidos com o LiquiBR. Cobre criação da cobrança, confirmação de pagamento via webhook, e reversão automática em caso de MED.

1. Setup inicial

1. Gere a API key e o webhook secret em Dashboard → API Keys & Webhooks. Guarde os dois no seu vault (env vars). A API key começa com pk_live_, o secret com whsec_.
2. Confirme que sua carteira USDT está cadastrada chamando GET /v1/account — confira que usdt_wallet.configured === true. Sem isso, charges criam normalmente mas o USDT fica pendente até o cadastro.
3. Configure sua URL de webhook em Dashboard → Webhooks ou passe webhook_url inline em cada charge.
4. Antes de produção: chame POST /v1/webhooks/test com sua URL e valide que seu validador HMAC funciona. Veja a resposta com signature_sent e timestamp_sent pra cross-check do seu lado.

2. Criar cobrança quando o cliente finaliza o pedido

Use o ID interno do seu pedido como external_id — isso te dá idempotência grátis e facilita reconciliação. Se o cliente clica "Pagar" duas vezes seguidas, você recebe a mesma charge (HTTP 200 + Idempotent-Replay: true) em vez de duplicar.

javascript// Quando o cliente confirma o pedido no CRM
async function gerarCobrancaPix(pedido) {
  const resp = await fetch('https://liquibr.com/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.LIQUIBR_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: pedido.valor_brl,
      external_id: `pedido-${pedido.id}`,    // chave de idempotência
      description: `${pedido.produto} - ${pedido.cliente.nome}`,
      webhook_url: 'https://seu-crm.com/webhooks/liquibr',
      customer: {
        name:     pedido.cliente.nome,
        email:    pedido.cliente.email,
        document: pedido.cliente.cpf
      }
    })
  });
  const charge = await resp.json();

  // 200 = idempotent_replay (cliente clicou 2x); 201 = nova charge
  // Os 2 retornam a mesma estrutura — pode usar igual

  // Mostra QR Code pro cliente pagar
  return {
    qr_code_image: charge.pix.qr_code_image_url,  // <img src=...>
    copia_cola:    charge.pix.copy_paste,
    expira_em:     charge.expires_at,
    liquibr_id:    charge.id
  };
}

3. Receber confirmação de pagamento via webhook

Quando o pagador paga, o LiquiBR envia pix.received pra sua URL. Valide a assinatura e marque o pedido como pago.

javascript// Express/Hono — endpoint /webhooks/liquibr
app.post('/webhooks/liquibr', express.raw({ type: 'application/json' }), async (req, res) => {
  // 1. Valida HMAC (ver seção "Validação HMAC")
  if (!validarAssinatura(req)) return res.status(401).send('invalid sig');

  const evento = JSON.parse(req.body.toString());
  const externalId = evento.data.charge.external_id;       // "pedido-12345"
  const pedidoId = externalId.replace('pedido-', '');

  // 2. Idempotência: ignora se já processamos esse webhook (via X-Webhook-Id)
  const whId = req.header('X-Webhook-Id');
  if (await jaProcessado(whId)) return res.status(200).json({ ok: true });

  // 3. Roteia por evento
  switch (evento.event) {
    case 'pix.received':
      await Pedido.update(pedidoId, {
        status: 'pago',
        pago_em: evento.data.charge.paid_at,
        psp_id:  evento.data.charge.psp_id
      });
      await liberarProduto(pedidoId);
      break;

    case 'pix.expired':
      await Pedido.update(pedidoId, { status: 'expirado' });
      break;

    case 'pix.med':
      // CRÍTICO: pagador acionou MED, dinheiro volta pra ele
      await Pedido.update(pedidoId, {
        status:     'estornado',
        med_em:     evento.data.med.marked_at,
        med_motivo: evento.data.med.reason
      });
      await reverterProduto(pedidoId);  // cancela acesso/devolve estoque
      break;

    case 'usdt.sent':
      // USDT chegou na carteira do lojista (informativo)
      await Pedido.update(pedidoId, {
        usdt_tx_hash: evento.data.transaction.tx_hash,
        usdt_rede:    evento.data.transaction.network
      });
      break;
  }

  await marcarProcessado(whId);
  res.status(200).json({ ok: true });
});

4. Reconciliação periódica (cinto + suspensório)

Mesmo com webhooks robustos, vale fazer reconciliação diária pra cobrir casos extremos (servidor seu fora do ar quando o webhook tentou as 3 vezes, MED disparado em janela de manutenção, etc):

javascript// Rotina diária (cron 03:00) — varre o dia anterior
async function reconciliarDiario() {
  const ontem = new Date(Date.now() - 86400000).toISOString().slice(0, 10);

  const { data: charges } = await fetch(
    `https://liquibr.com/v1/charges?date_from=${ontem}&date_to=${ontem}&limit=200`,
    { headers: { 'Authorization': `Bearer ${process.env.LIQUIBR_API_KEY}` } }
  ).then(r => r.json());

  for (const c of charges) {
    const pedidoId = c.external_id?.replace('pedido-', '');
    if (!pedidoId) continue;

    const pedido = await Pedido.find(pedidoId);
    if (!pedido) continue;

    // Detecta divergências entre LiquiBR e seu CRM
    if (c.status === 'paid' && pedido.status !== 'pago') {
      console.warn(`PED ${pedidoId}: LiquiBR marcou pago, CRM não recebeu webhook`);
      await Pedido.update(pedidoId, { status: 'pago', pago_em: c.paid_at });
    }
    if (c.status === 'refunded' && pedido.status === 'pago') {
      console.warn(`PED ${pedidoId}: charge refunded mas CRM ainda pago — MED não processado`);
      await reverterProduto(pedidoId);
    }
  }
}

5. Cancelamento manual

Quando o cliente cancela o pedido no CRM antes de pagar, cancele a charge correspondente pra não deixar pending no painel:

javascriptasync function cancelarPedido(pedidoId) {
  await fetch(`https://liquibr.com/v1/charges/pedido-${pedidoId}`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${process.env.LIQUIBR_API_KEY}` }
  });
  // Charge fica em refunded. Se já estava paga, retorna 409 — aí abra ticket pra estorno.
}

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.3 · 2026-05-30
  • Novos endpoints: DELETE /v1/charges/{id} (cancelar pending), POST /v1/webhooks/test (validar integração), GET /v1/webhooks/deliveries (auditoria).
  • Endpoint POST /v1/charges/{id}/refund documentado (retorna 501 — estornos seguem via suporte por enquanto).
  • GET /v1/charges: novos filtros date_from, date_to, payer_document, customer_email pra reconciliação.
  • Suporte ao header Idempotency-Key (padrão Stripe-like) como alternativa ao external_id no body.
  • Webhook pix.med documentado — dispara quando o operador marca devolução PIX.
  • max_charge_brl default subiu de R$ 200 → R$ 500.
  • Domínio principal migrado de liquibr.com → liquibr.com. URL antiga ainda resolve mas o canônico é o .trade.
  • Headers X-Webhook-Source e X-Webhook-Id documentados (já eram enviados desde v1.1 — agora cobertos formalmente).
  • Rate limit corrigido na doc: 100 requisições/minuto por IP (a doc anterior mencionava 50k/24h global, mas isso nunca foi implementado).
• 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.