Concepts
Overview
PayZu Processamento is a REST API with 29 endpoints split across 7 groups. All communication happens in JSON, over HTTPS, with Bearer token. Monetary values are always in reais (BRL), not in cents.
The 7 endpoint groups
| Group | Endpoints | What it does |
|---|---|---|
| Pix charges | 4 | Create and query Pix charges (deposits), QR Code, receipt. |
| Withdrawals | 6 | Send Pix by key or QR Code, DICT lookup, QR parsing. |
| Internal transfer | 2 | Move balance between PayZu accounts, instant. |
| Account | 2 | Profile, permissions, limits and balance. |
| Reports | 6 | List transactions, generate async CSV. |
| Callbacks | 4 | Inspect and resend webhooks. |
| Infractions (MED) | 5 | Pix disputes initiated by the payer and defense submission. |
Transaction model
Every movement at PayZu is represented by a transaction. Whether it's a charge, withdrawal or internal transfer, the basic structure is the same.
Main fields
| Field | Type | Purpose |
|---|---|---|
id | string | Unique identifier of the transaction at PayZu. |
type | string | DEPOSIT, WITHDRAW or INTERNAL_TRANSFER. |
status | string | Current state. The most common ones: PENDING, COMPLETED, REFUNDED, EXPIRED, ERROR. |
amount | number | Value in reais (BRL), not in cents. E.g.: 10.90 is R$ 10.90. |
clientReference | string | Your external identifier. Returns in every callback. Use it for idempotência and lookup. |
virtualAccount | string | Virtual subaccount (up to 50 chars). Use it for multi-tenant (stores, branches, marketplaces). |
callbackUrl | string | URL to receive status updates via webhook. |
endToEndId | string | Unique identifier of the operation at Bacen. Useful for tracking in disputes. |
All fields detailed in the Glossary.
Typical lifecycle
Full states by type in each endpoint reference. Quick table in the Glossary · Transaction status.
API conventions
| Item | Value |
|---|---|
| Base URL | https://api.payzu.processamento.com/v1 |
| Authentication | Authorization: Bearer YOUR_TOKEN |
| Content-Type | application/json (required on every call) |
| Values | In reais (BRL), never in cents |
| Dates | ISO 8601 (2025-11-23T10:46:26.986Z) |
| Encoding | UTF-8 |
| Pagination | page + limit with hasNextPage flag |
| Webhooks | POST to callbackUrl, retry up to 72x |