Conceitos
O mapa mental antes da primeira chamada: o que a API cobre, como as operações se agrupam e o que é uma transação na PayZu, tudo em reais e sobre HTTPS.
Visão geral
A PayZu Processamento é uma API REST com endpoints divididos em grupos funcionais. Toda a comunicação acontece em JSON, sobre HTTPS, com Bearer token. Valores monetários estão sempre em reais (BRL).
Grupos de endpoints
O inventário completo dos grupos, com os endpoints de cada um, está na referência da API.
Modelo de transação
Toda movimentação na PayZu é representada por uma transação. Independente de ser cobrança, saque ou transferência interna, a estrutura básica é a mesma.
Campos principais
| Campo | Tipo | Para que serve |
|---|---|---|
id | string | Identificador único da transação na PayZu. |
type | string | DEPOSIT, WITHDRAW ou COMMISSION. |
method | string | PIX, BANK_SLIP ou INTERNAL_TRANSFER. |
status | string | Estado atual. Os mais comuns: PENDING, COMPLETED, REFUNDED, EXPIRED, ERROR. |
amount | number | Valor em reais (BRL). Ex: 10.90 é R$ 10,90. |
clientReference | string | Seu identificador externo. Volta em todo callback. Use para idempotência e lookup. |
virtualAccount | string | Subconta virtual (até 50 chars). Use para multi-tenant (lojas, filiais, marketplaces). |
callbackUrl | string | URL para receber atualizações de status via webhook. |
endToEndId | string | Identificador único da operação no Bacen. Útil para rastrear em disputas. |
Todos os campos detalhados no Glossário.
Ciclo de vida típico
Estados completos por tipo na referência de cada endpoint. Tabela rápida no Glossário · Status de transação.
Convenções da API
| Item | Valor |
|---|---|
| Base URL | https://api.payzu.processamento.com/v1 |
| Autenticação | Authorization: Bearer SEU_TOKEN |
| Content-Type | application/json (obrigatório em toda chamada) |
| Valores | Em reais (BRL), nunca em centavos |
| Datas | ISO 8601 (2025-11-23T10:46:26.986Z) |
| Encoding | UTF-8 |
| Paginação | page + limit com flag hasNextPage |
| Webhooks | POST em callbackUrl, retry até 72x |
Próximos passos
Webhooks
Em vez de ficar perguntando se o pagamento caiu, a gente avisa o seu servidor no instante em que o status muda, e insiste com novas tentativas espaçadas por até 72 vezes se o seu sistema não responder.
Tutoriais
Passo a passo dos fluxos que você realmente coloca em produção, de receber um Pix simples até responder uma disputa MED, com código pronto pra copiar em curl, Node, Python, Go e PHP.