Primeiros passos

Autenticação Depósitos Saques Webhooks Glossário

Criar conta

Abra sua conta em abrirconta.payzu.com.br. Após aprovação você recebe:

Bearer token, usado em todas as requisições. Ver Autenticação.
Base URL, https://pix.payzu.io/v1.

Guarde o token em vault (Google Secret Manager, AWS Secrets, etc). Nunca commite em repositório nem exponha no front-end.

Validar autenticação

Para confirmar que o token funciona, consulte o saldo via GET /user/balance.

curl https://pix.payzu.io/v1/user/balance \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json"

const res = await fetch('https://pix.payzu.io/v1/user/balance', {
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
});
const balance = await res.json();

Se voltar o JSON com o saldo, está autenticado. Se retornar 401, revise o token. Ver códigos HTTP no glossário.

Criar a primeira cobrança Pix

Crie uma cobrança via POST /pix. Schema completo na referência.

curl -X POST https://pix.payzu.io/v1/pix \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.90,
    "generatedName": "João da Silva",
    "generatedDocument": "12345678909",
    "callbackUrl": "https://seusite.com.br/webhooks/payzu",
    "clientReference": "pedido-2025-001"
  }'

const res = await fetch('https://pix.payzu.io/v1/pix', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10.90,
    generatedName: 'João da Silva',
    generatedDocument: '12345678909',
    callbackUrl: 'https://seusite.com.br/webhooks/payzu',
    clientReference: 'pedido-2025-001',
  }),
});
const charge = await res.json();

A resposta traz qrCodeText (copia-e-cola), qrCodeUrl e o id da transação.

Valores estão sempre em reais (BRL), não em centavos. 10.90 é R$ 10,90.

Receber o callback

Quando o pagador concluir o Pix, a PayZu envia um POST para a callbackUrl informada com a transação atualizada (status: "COMPLETED"). Responda com 2xx em até 5 segundos.

POST /webhooks/payzu
Content-Type: application/json

{
  "id": "PZ_xxx",
  "status": "COMPLETED",
  "amount": 10.90,
  "clientReference": "pedido-2025-001",
  "endToEndId": "E18236120202511231046s1235ee7",
  "paidAt": "2026-05-21T10:46:26.986Z"
}

Detalhes de retry, payload completo e segurança em Webhooks.

Próximos passos

Fazer um saque Consultar extrato Try-it no Scalar