Getting started

Authentication Deposits Withdrawals Webhooks Glossary

Create account

Open your account at abrirconta.payzu.com.br. After approval you receive:

Bearer token, used in every request. See Authentication.
Base URL, https://pix.payzu.io/v1.

Store the token in a vault (Google Secret Manager, AWS Secrets, etc). Never commit it to a repository or expose it on the front-end.

Validate authentication

To confirm the token works, check the balance via GET /user/balance.

curl https://pix.payzu.io/v1/user/balance \
  -H "Authorization: Bearer YOUR_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();

If you get back a JSON with the balance, you're authenticated. If it returns 401, double-check the token. See HTTP codes in the glossary.

Create the first Pix charge

Create a charge via POST /pix. Full schema in the reference.

curl -X POST https://pix.payzu.io/v1/pix \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.90,
    "generatedName": "João da Silva",
    "generatedDocument": "12345678909",
    "callbackUrl": "https://yoursite.com/webhooks/payzu",
    "clientReference": "order-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://yoursite.com/webhooks/payzu',
    clientReference: 'order-2025-001',
  }),
});
const charge = await res.json();

The response contains qrCodeText (copy-and-paste), qrCodeUrl and the transaction id.

Amounts are always in reais (BRL), not cents. 10.90 is R$ 10.90.

Receive the callback

When the payer completes the Pix, PayZu sends a POST to the callbackUrl you provided with the updated transaction (status: "COMPLETED"). Respond with 2xx within 5 seconds.

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

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

Retry details, full payload and security in Webhooks.

Next steps

Make a withdrawal Check statement Try it on Scalar