Confirmar uma cobrança Pix pelo webhook
Mande client_id e client_secret em Basic, com grant_type client_credentials. O token vale 15 minutos.
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.
Entregue pix.qrCodeText ao cliente ou desenhe o QR Code a partir dele.
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.
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.
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)
{ "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