Documentação da API

Autenticação

Toda requisição usa HTTP Basic com as credenciais do painel.

Authorization: Basic base64(CLIENT_ID:SECRET)

# ou, se preferir:
Authorization: Bearer CLIENT_ID:SECRET

Criar cobrança PIX

POST /api/v1/transactions

{
  "amount": 50.00,
  "external_id": "pedido-1001",
  "description": "Depósito na conta",
  "payer": {
    "name": "Maria Silva",
    "document": "12345678901",
    "email": "maria@email.com",
    "phone": "11999998888"
  },
  "postback_url": "https://seusite.com/webhook",
  "metadata": { "user_id": 42 }
}

amount em reais, ou use amount_cents em centavos. Mínimo R$ 1,00. external_id garante idempotência: repetir o mesmo valor devolve a cobrança existente em vez de criar outra.

Resposta 201

{
  "id": "128",
  "external_id": "pedido-1001",
  "status": "pending",
  "amount": 50,
  "fee": 1.5,
  "net": 48.5,
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_image": "data:image/png;base64,iVBORw0...",
    "expires_at": "2026-07-21T12:00:00.000Z"
  },
  "payer": { "name": "Maria Silva", ... },
  "paid_at": null,
  "created_at": "2026-07-20T12:00:00.000Z"
}

Consultar status

GET /api/v1/transactions?external_id=pedido-1001
GET /api/v1/transactions?id=128

Webhook

Quando o pagamento é confirmado, enviamos um POST para a URL cadastrada (ou postback_url da cobrança).

POST https://seusite.com/webhook
X-SeuPagg-Signature: <hmac_sha256>
X-SeuPagg-Delivery: 91
X-SeuPagg-Attempt: 1

{
  "event": "transaction.paid",
  "transaction": {
    "id": "128",
    "external_id": "pedido-1001",
    "status": "paid",
    "amount": 50,
    "net": 48.5,
    "paid_at": "2026-07-20T12:05:00.000Z",
    "payer": { "name": "Maria Silva", "document": "12345678901" },
    "metadata": { "user_id": 42 }
  }
}

Validando a assinatura

// Node.js
const crypto = require("crypto");

const assinatura = crypto
  .createHmac("sha256", SEU_WEBHOOK_SECRET)
  .update(corpoBrutoDaRequisicao)
  .digest("hex");

if (assinatura !== req.headers["x-seupagg-signature"]) {
  return res.status(401).end();
}

Responda 200 para confirmar. Qualquer outro código faz o reenvio com espera progressiva (1min, 5min, 15min, 1h, 3h, 12h).

Eventos

Erros