PayZu Conta HubTutoriais

Confirmar uma cobrança Pix pelo webhook

  1. Mande client_id e client_secret em Basic, com grant_type client_credentials. O token vale 15 minutos.

  2. O valor vai em centavos: 1500 é R$ 15,00. Para usar callbackUrl, a conta precisa do segredo de callback, emitido em POST /transactions/callback-secret.

  3. Entregue pix.qrCodeText ao cliente ou desenhe o QR Code a partir dele.

  4. Calcule o HMAC-SHA256 de <X-Payzu-Timestamp>.<corpo cru> com o segredo de callback e compare em tempo constante com o valor depois de sha256=. Recuse timestamp fora da tolerância que você definir; o exemplo usa 5 minutos.

  5. No PAYMENT_PAID, libere o pedido pelo externalRef e responda 2xx em até 10 segundos. O mesmo webhook pode chegar de novo: descarte repetidos pelo X-Payzu-Delivery.

confirm-charge-by-webhook.js
import crypto from 'node:crypto'import http from 'node:http' const API = 'https://api.sandbox.payzu.dev/api/v1'const basic = Buffer.from(`${process.env.PAYZU_CLIENT_ID}:${process.env.PAYZU_CLIENT_SECRET}`).toString('base64') const { access_token } = await fetch(`${API}/oauth/token`, {  method: 'POST',  headers: { authorization: `Basic ${basic}` },  body: new URLSearchParams({ grant_type: 'client_credentials' })}).then((r) => r.json()) const charge = await fetch(`${API}/transactions/payment`, {  method: 'POST',  headers: { authorization: `Bearer ${access_token}`, 'content-type': 'application/json' },  body: JSON.stringify({    amount: 1500,    method: 'PIX',    description: 'Pedido 4821',    externalRef: 'pedido-4821',    customer: { name: 'Maria Souza', document: '52998224725' },    callbackUrl: 'https://sualoja.com.br/webhooks/payzu'  })}).then((r) => r.json())console.log(charge.status, charge.pix.qrCodeText) function isSigned(raw, headers) {  const timestamp = headers['x-payzu-timestamp'] ?? ''  const signature = /^sha256=([0-9a-f]{64})$/i.exec(headers['x-payzu-signature'] ?? '')  if (!signature || !/^\d+$/.test(timestamp)) return false  if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) return false  const expected = crypto.createHmac('sha256', process.env.PAYZU_CALLBACK_SECRET).update(`${timestamp}.${raw}`).digest()  return crypto.timingSafeEqual(expected, Buffer.from(signature[1], 'hex'))} http.createServer(async (req, res) => {  const chunks = []  for await (const chunk of req) chunks.push(chunk)  const raw = Buffer.concat(chunks).toString()  if (!isSigned(raw, req.headers)) return res.writeHead(401).end()  const { event, data } = JSON.parse(raw)  if (event === 'PAYMENT_PAID') console.log('pago', data.externalRef, data.netAmount)  res.writeHead(200).end()}).listen(3000)
Resposta · 200 Cobrança já existente
{  "id": "P20261005113205K7Q2M9XB4TC127431",  "method": "PIX",  "status": "PENDING",  "amount": 1500,  "description": "Pedido 4821",  "serviceFee": 105,  "netAmount": 1395,  "refundedAmount": 0,  "refundFee": 0,  "refundInProgressAmount": 0,  "refundableAmount": 0,  "openInfractionProtocol": null,  "externalRef": "pedido-4821",  "callbackUrl": null,  "createdAt": "2026-10-05T14:32:05.123Z",  "paidAt": null,  "refundedAt": null,  "pix": {    "qrCodeText": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4",    "endToEndId": null  },  "customer": {    "name": "Maria Souza",    "document": "52998224725",    "email": "maria.souza@exemplo.com",    "phone": "+5511999998888"  },  "payer": null,  "refunds": []}

Referência: Criar uma cobrança Pix com copia e cola