API Pimenta Pay

Use a Pimenta Pay como gateway PIX do seu site, checkout ou sistema. Você cria a cobrança pela API, mostra o QR Code ao cliente e recebe um webhook assinado quando o pagamento é confirmado.

URL base: https://blackpays.site/api/public/v1

Todos os valores são em centavos (R$ 10,00 = 1000). Datas em ISO 8601 (UTC). As mesmas taxas do painel valem para cobranças pela API.

Autenticação

Crie uma chave em Painel → API & Webhooks → Chaves. Ela aparece só uma vez. Envie em todas as requisições:

Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx

Nunca coloque a chave no navegador ou app do cliente — chame a API só do seu servidor. Se vazar, revogue no painel.

Criar cobrança PIX

POST/pix

curl -X POST https://blackpays.site/api/public/v1/pix \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 4990,
    "description": "Pedido 1234",
    "customerName": "Maria Souza",
    "customerEmail": "maria@email.com",
    "externalRef": "pedido-1234",
    "tracking": { "utm_source": "facebook", "utm_campaign": "black" }
  }'

Resposta 201:

{
  "id": "TX_...",
  "externalRef": "pedido-1234",
  "status": "pending",
  "amountCents": 4990,
  "pixCopyPaste": "00020126...",
  "qrCodeBase64": "iVBORw0KGgo..." ,
  "expiresAt": "2026-10-09T13:00:00.000Z"
}

Mostre pixCopyPaste (copia e cola) e o QR Code (data:image/png;base64, + qrCodeBase64).

Consultar cobrança

GET/pix/{id}

curl https://blackpays.site/api/public/v1/pix/TX_... -H "Authorization: Bearer SUA_CHAVE"

{ "id": "TX_...", "status": "paid", "amountCents": 4990, "netCents": 4586,
  "feeCents": 404, "description": "Pedido 1234", "paidAt": "...", "createdAt": "...", "expiresAt": "..." }

Listar cobranças

GET/pix?limit=20&status=paid&externalRef=pedido-1234&before=2026-10-01T00:00:00Z

Mais recentes primeiro. limit até 100; use before com o createdAt do último item para paginar.

{ "data": [ { "id": "TX_...", "externalRef": "pedido-1234", "status": "paid", ... } ] }

Saldo

GET/balance

{ "availableCents": 12550, "processingCents": 0, "totalReceivedCents": 50000, "currency": "BRL" }

Webhooks

Cadastre sua URL https em Painel → API & Webhooks → Webhook. Enviamos um POST JSON a cada evento:

POST https://seusite.com/webhook
X-BlackPay-Event: payment.paid
X-BlackPay-Signature: 5f2b9c...(HMAC-SHA256 hex)

{
  "id": "b1f0...-uuid-da-entrega",
  "event": "payment.paid",
  "createdAt": "2026-10-09T12:31:04.000Z",
  "data": {
    "id": "TX_...", "externalRef": "pedido-1234", "status": "paid",
    "amountCents": 4990, "netCents": 4586, "feeCents": 404,
    "description": "Pedido 1234", "paidAt": "2026-10-09T12:31:00.000Z",
    "customerName": "Maria Souza", "customerEmail": "maria@email.com",
    "tracking": { "utm_source": "facebook", "utm_campaign": "black" }
  }
}

Responda com status 2xx em até 8 segundos. Use o campo id para ignorar entregas repetidas, e se quiser confirmar, consulte GET /pix/{id} antes de liberar. Todo envio aparece em "Últimos envios" no painel.

Validar assinatura

Calcule o HMAC-SHA256 do corpo bruto com o seu segredo (whsec_...) e compare com o cabeçalho.

// Node.js / Express
import crypto from "node:crypto";
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", process.env.BLACKPAY_WEBHOOK_SECRET)
    .update(req.body).digest("hex");
  const got = req.get("X-BlackPay-Signature") || "";
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected)))
    return res.status(401).end();
  const evt = JSON.parse(req.body.toString());
  if (evt.event === "payment.paid") { /* liberar pedido evt.data.externalRef */ }
  res.sendStatus(200);
});

<?php // PHP
$body = file_get_contents("php://input");
$sig = hash_hmac("sha256", $body, getenv("BLACKPAY_WEBHOOK_SECRET"));
if (!hash_equals($sig, $_SERVER["HTTP_X_BLACKPAY_SIGNATURE"] ?? "")) { http_response_code(401); exit; }
$evt = json_decode($body, true);

Status da cobrança

Erros

UTMs e UTMify

Envie as UTMs em tracking. Se você conectar a UTMify em Painel → Integrações, cada PIX gerado, pago ou estornado vai sozinho para a sua UTMify, com valor, taxa e UTMs — inclusive cobranças feitas pela API.