The mental map before your first call: what the API covers, how its operations are grouped, and what a transaction is at PayZu, all in reais and over HTTPS.
Overview
PayZu Processamento is a REST API with endpoints split across functional groups. All communication happens in JSON, over HTTPS, with Bearer token. Monetary values are always in reais (BRL).
Endpoint groups
The full inventory of groups, with the endpoints in each one, lives in the API reference.
Transaction model
Every movement at PayZu is represented by a transaction. Whether it's a charge, Pix payment 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 COMMISSION. |
method | string | PIX, BANK_SLIP or INTERNAL_TRANSFER. |
status | string | Current state. The most common ones: PENDING, COMPLETED, REFUNDED, EXPIRED, ERROR. |
amount | number | Value in reais (BRL). 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 (2026-08-11T10:46:26.986Z) |
| Encoding | UTF-8 |
| Pagination | page + limit; the envelope varies per route (details) |
| Webhooks | POST to callbackUrl, retry up to 40x |