PayZu GatewayTutoriais

Receber por link de pagamento

  1. As rotas do link e da fatura não pedem credencial. Confira available e se pix está em payment_settings.accepted_methods.

  2. A compra não tem corpo e cria uma fatura sem cliente. Cada chamada cria outra fatura, então chame uma vez por compra.

  3. Na fatura sem cliente, customer vai na primeira tentativa. Com o desconto do link no Pix, a tentativa já sai com o valor descontado.

  4. Entregue pix.qr_code_text, o copia e cola, ou desenhe o QR Code a partir dele, porque qr_code_url vem null. Ele vale até pix.expires_at, 60 minutos depois. Sem resposta da adquirente, a tentativa vem processing, sem o QR Code, e passa a pending quando a cobrança aparece. Recusado, o Pix vem failed, com o motivo em failure.message.

  5. Consulte a fatura enquanto estiver pending. No 429 do limite por IP, readInvoice espera um minuto e consulta de novo. Com status paid, a fatura é o comprovante; leve o comprador para checkout.redirect_url, quando houver.

payment-link.js
const API = 'https://api.sandbox.payzu.dev/v1/checkout'const linkId = 'pl_4NwK8xQcLb3MzYv7TdRh5E'const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))const readInvoice = async (id) => {  while (true) {    const response = await fetch(`${API}/invoices/${id}`)    const body = await response.json()    if (response.ok) return body    if (response.status !== 429) throw new Error(body.message)    await wait(60000)  }} const link = await fetch(`${API}/payment-links/${linkId}`).then((r) => r.json())if (!link.available || !link.payment_settings.accepted_methods.includes('pix')) throw new Error('Link indisponível para Pix')console.log(link.name, link.amount, link.discount?.public_description) const purchase = await fetch(`${API}/payment-links/${linkId}/invoices`, { method: 'POST' })let invoice = await purchase.json()if (!purchase.ok) throw new Error(invoice.message)console.log(invoice.id, invoice.url) const response = await fetch(`${API}/invoices/${invoice.id}/payments`, {  method: 'POST',  headers: { 'content-type': 'application/json' },  body: JSON.stringify({    method: 'pix',    customer: {      name: 'João Lima', email: 'joao@exemplo.com.br', phone: '21998765432',      document: '11144477735', document_type: 'cpf',      address: {        street: 'Avenida Paulista', number: '1000', district: 'Bela Vista',        city: 'São Paulo', state: 'SP', zip_code: '01310100', country: 'BR'      }    }  })})invoice = await response.json()if (!response.ok) throw new Error(invoice.message) const pixOf = (current) => current.payments.find((payment) => payment.method === 'pix')while (invoice.status === 'pending' && pixOf(invoice).status === 'processing') {  await wait(5000)  invoice = await readInvoice(invoice.id)}const attempt = pixOf(invoice)if (invoice.status === 'pending') {  if (attempt.status !== 'pending') throw new Error(attempt.failure?.message ?? `Pix ${attempt.status}`)  console.log(attempt.amount, attempt.pix.expires_at)  console.log(attempt.pix.qr_code_text)   while (invoice.status === 'pending' && Date.now() < Date.parse(attempt.pix.expires_at)) {    await wait(5000)    invoice = await readInvoice(invoice.id)  }}if (invoice.status === 'paid') console.log('paga em', invoice.billing.paid_at, invoice.checkout.redirect_url)
Resposta · 201 Fatura criada
{  "id": "in_6YtR3nMcXb9LwQz4KdVh8E",  "status": "pending",  "url": "https://invoice.payzu.com.br/pay/in_6YtR3nMcXb9LwQz4KdVh8E",  "description": "Ingresso do workshop",  "created_at": "2026-11-11T15:50:02.630Z",  "updated_at": "2026-11-11T15:50:02.630Z",  "amounts": {    "subtotal": 12000,    "discount": 0,    "total": 12000,    "paid": 0,    "refunded": 0  },  "billing": {    "cycle_number": null,    "due_at": "2026-11-11T15:50:02.630Z",    "expires_at": "2026-11-26T15:50:02.630Z",    "paid_at": null,    "canceled_at": null,    "refunded_at": null,    "chargedback_at": null  },  "items": [    {      "name": "Ingresso do workshop",      "sku": null,      "quantity": 1,      "unit_price": 12000    }  ],  "payment_settings": {    "accepted_methods": [      "credit_card",      "pix"    ],    "credit_card": {      "max_installments": 12    }  },  "checkout": {    "redirect_url": null,    "cancel_url": null  },  "merchant": {    "display_name": "Loja da Maria"  },  "customer": null,  "subscription": null,  "payment_link": {    "id": "pl_gVRWtMpkRuCnRuqzEy28zv",    "name": "Ingresso do workshop",    "discount": null  },  "payments": [],  "refunds": []}

Referência: Comprar pelo link