API PixFeito

REST + JSON. Base: https://pixfeito.com.br/api/v1. Respostas no envelope { success, data }.

Autenticação

Gere uma chave em Painel → API e webhooks. Cada chave pertence a uma empresa e tem escopos (charges:read, charges:write, pix:read, customers:read, customers:write).

Authorization: Bearer pc_live_xxxxxxxxxxxxxxxx

Erros e limites

400 JSON inválido · 401 chave inválida · 403 sem escopo · 404 não encontrado · 422 validação (errors por campo) · 429 limite (120 req/min por chave) · 502 o banco recusou.

Envie Idempotency-Key no POST de cobrança: a mesma chave com o mesmo corpo devolve a mesma resposta por 24h — retentativas do seu PDV nunca duplicam cobrança.

Cobranças

Criar — POST /charges

curl -X POST https://pixfeito.com.br/api/v1/charges \
  -H "Authorization: Bearer pc_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: PDV-10432" \
  -d '{
    "amount": 149.90,
    "description": "Venda 10432",
    "order_number": "10432",
    "external_reference": "PDV-10432",
    "expiration_seconds": 1800,
    "customer": { "name": "Maria Souza", "phone": "5521999998888", "document": "12345678909" },
    "metadata": { "loja": "centro" }
  }'

Também aceita amount_cents, connection_id (força uma conta), customer_id e static_qr: true (QR estático com txid, sem chamar o banco).

{
  "success": true,
  "data": {
    "id": "9b2f…",
    "txid": "PCk3…",
    "status": "pending",
    "amount": 149.9,
    "amount_cents": 14990,
    "pix_copy_paste": "00020101021226…6304ABCD",
    "qr_code_base64": "data:image/png;base64,iVBOR…",
    "payment_url": "https://pixfeito.com.br/p/<token>",
    "expires_at": "2026-10-29T15:00:00.000Z"
  }
}

Listar — GET /charges

Filtros: status, external_reference, date_from, date_to, page, per_page.

Consultar — GET /charges/{id}

Inclui payments (os Pix vinculados).

Cancelar — POST /charges/{id}/cancel

Devolver — POST /charges/{id}/refund

{ "amount_cents": 5000 } (vazio = total). Responde 202; o status final chega por webhook charge.refunded.

Radar Pix — GET /pix

Todos os Pix recebidos nas contas conectadas, vinculados ou não. Filtros: date_from, date_to, unmatched=true, page, per_page.

Clientes — GET/POST /customers

Campos: name, phone, email, document, notes, metadata. GET aceita search.

Webhooks

Cadastre a URL no painel. Eventos: charge.paid, pix.received, pix.unmatched, charge.created, charge.expired, charge.cancelled, charge.refunded.

POST https://seu-erp.com.br/webhooks/pix
X-PixCaiu-Event: charge.paid
X-PixCaiu-Delivery: 3f1c…
X-PixCaiu-Signature: t=1761748328,v1=5d2f…

{ "id": "charge.paid:9b2f…", "type": "charge.paid", "created_at": "…",
  "data": { "charge": { … }, "pix": { "end_to_end_id": "E1234…", "payer_name": "Maria Souza", … } } }

Valide: v1 = HMAC_SHA256(secret, t + "." + corpo_bruto) e rejeite se t tiver mais de 5 minutos.

// Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
const [t, v1] = sig.split(',').map(p => p.split('=')[1]);
const ok = Math.abs(Date.now()/1000 - Number(t)) < 300 &&
  timingSafeEqual(Buffer.from(v1), Buffer.from(createHmac('sha256', SECRET).update(t + '.' + rawBody).digest('hex')));

Responda 2xx em até 10s. Falhas são reenviadas em 10s, 30s, 2min, 10min, 30min, 2h, 6h e 12h. Use id do evento para idempotência.

Status da cobrança