PagarPrivado · Developers

Aceite "Pagar Privado" no seu site

Adicione pagamento privado ao seu checkout em minutos — igual a um Pix normal, mas o cliente não expõe os dados dele e você não expõe os seus. Você cria a cobrança, redireciona para o nosso checkout hospedado e recebe um webhook assinado quando o pagamento cai. Grátis para integrar: basta uma conta (login com Google).

Como funciona

1. No seu checkout, o cliente clica em Pagar Privado.
2. Seu backend chama POST /api/v1/charges — nasce uma cobrança com QR + código Pix únicos e um checkoutUrl.
3. Você redireciona o cliente ao checkoutUrl: ele vê QR e valor, paga no banco dele, e a tela fica em "Confirmando…" sozinha.
4. O dinheiro cai na SUA chave Pix em segundos e chamamos o SEU webhook com charge.paid (assinado). Você libera o pedido — manual ou automático.
5. Com returnUrl, o cliente volta ao seu site depois de pagar.

Autenticação

Entre em pagarprivado.com com Google → Conta → Gerar chave de API. A chave é mostrada uma única vez — guarde no seu servidor, nunca no navegador.

Authorization: Bearer pp_live_sua_chave

Limites: 60 req/min (grátis) · 300 req/min (PLUS). Sem mensalidade para usar a API — a taxa fixa por Pix cobre o serviço.

POST /api/v1/charges — criar cobrança

CampoTipoObrigatório
amountReaisstring ("99,90")sim*
amountCentsinteiro (9990)sim*
destinationKeychave Pix destino (default: a da sua conta)não
feeMode"buyer_pays" (default) | "seller_pays"não
returnUrlhttps — para onde o cliente volta após pagarnão

* informe amountReais OU amountCents. Cada chamada gera QR e código únicos — o mesmo produto pode ter infinitos links, um por comprador.

curl -X POST https://www.pagarprivado.com/api/v1/charges \
  -H "Authorization: Bearer pp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amountReais":"99,90","returnUrl":"https://sualoja.com/obrigado"}'

Resposta (principais campos):

{
  "paymentRequest": {
    "token": "PP4F2A9C01",
    "confirmationCode": "4821",
    "checkoutUrl": "https://www.pagarprivado.com/pay/PP4F2A9C01",
    "pixCopiaECola": "000201...",
    "pixQrCodeImage": "data:image/png;base64,...",
    "status": "created",
    "amountCents": 9990, "feeCents": 399, "totalCents": 10389
  }
}

GET /api/v1/charges/:token — status

created (aguardando) → claimed (pago, repassando) → routed (concluído: dinheiro na sua chave). refunded = não concluído, valor devolvido ao pagador. failed = não concluído. Trate qualquer status diferente de routed como venda não concluída — novos estados podem aparecer.

Webhook charge.paid — saiba na hora que caiu

Configure a URL do seu webhook na sua Conta. Você recebe um pp_whsec_... (mostrado uma vez) e cada POST vem assinado — padrão igual ao do Stripe:

POST https://sualoja.com/webhooks/pagarprivado
PagarPrivado-Signature: t=1719900000,v1=hex(hmac_sha256(secret, t + "." + body))

{
  "event": "charge.paid",
  "data": {
    "token": "PP4F2A9C01",
    "confirmationCode": "4821",
    "amountCents": 9990, "feeCents": 399, "totalCents": 10389,
    "feeMode": "buyer_pays",
    "paidAt": "2026-07-02T12:00:00.000Z"
  }
}

Verificação em Node:

const crypto = require("node:crypto");
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(parts.t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(parts.v1, "hex"), Buffer.from(expected, "hex"));
}
// verificou? → libere o pedido do token correspondente.

Entrega com retentativas (0s, 10s, 60s). Responda 2xx. Use o token para casar com o pedido — e o confirmationCode para conferência humana.

Botão pronto (2 linhas no seu site)

É assim que o botão aparece no seu checkout (cores e marca do PagarPrivado):

Crie no SEU backend um endpoint que chama /api/v1/charges e devolve {"url": checkoutUrl}. Depois:

<div class="pagarprivado-button" data-endpoint="/meu-endpoint-pp"></div>
<script src="https://www.pagarprivado.com/button.js" async></script>

O script desenha o botão Pagar Privado, chama seu endpoint no clique e leva o cliente ao checkout. Sua chave de API fica só no seu servidor.

Exemplo do endpoint (Node/Express):

app.post("/meu-endpoint-pp", async (req, res) => {
  const r = await fetch("https://www.pagarprivado.com/api/v1/charges", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.PAGARPRIVADO_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ amountReais: "99,90", returnUrl: "https://sualoja.com/obrigado" }),
  }).then(r => r.json());
  res.json({ url: r.paymentRequest.checkoutUrl });
});

Notas

← Voltar ao app