Paginação
Percorra listas grandes de transações, callbacks e infrações página por página, sabendo pela resposta se ainda há mais; para janelas longas, prefira o relatório assíncrono em CSV.
Endpoints que listam recursos (/user/transactions, /user/callbacks, /user/infractions) usam paginação clássica por page + limit com flag hasNextPage.
Padrão de loop
PAGE=1
LIMIT=100
while : ; do
RESP=$(curl -s "https://api.payzu.processamento.com/v1/user/transactions?dateFrom=2025-11-01&page=$PAGE&limit=$LIMIT" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json")
echo "$RESP" | jq -c '.data[]'
HAS_NEXT=$(echo "$RESP" | jq -r '.hasNextPage')
[ "$HAS_NEXT" != "true" ] && break
PAGE=$((PAGE+1))
doneasync function* iterateTransactions(filters: Record<string, string>) {
let page = 1;
const limit = 100;
while (true) {
const params = new URLSearchParams({ ...filters, page: String(page), limit: String(limit) });
const res = await fetch(`https://api.payzu.processamento.com/v1/user/transactions?${params}`, {
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Content-Type': 'application/json',
},
});
const { data, hasNextPage } = await res.json();
for (const tx of data) yield tx;
if (!hasNextPage) return;
page++;
}
}
for await (const tx of iterateTransactions({ dateFrom: '2025-11-01' })) {
await process(tx);
}Filtros disponíveis
| Filtro | Quando usar |
|---|---|
dateFrom / dateTo | Janela temporal (ISO 8601). |
clientReference | Encontra a transação correspondente ao seu pedido. |
virtualAccount | Filtro por tenant (multi-loja). |
status | CSV: COMPLETED,PENDING. Aceita múltiplos. |
type | CSV: DEPOSIT,WITHDRAW,COMMISSION. |
endToEndId | Identificador único Bacen. |
document, name | Filtros por pagador. document apenas dígitos (11 ou 14). |
amount | Filtro por valor exato. |
Limite e tamanho da página
| Item | Valor |
|---|---|
limit max | 100 por página |
| Default | 20 |
Páginas grandes demais degradam latência. Se precisa de período longo (mês, ano) ou exportar tudo, prefira o relatório assíncrono.
Quando usar relatório assíncrono em vez de paginar
| Cenário | Recomendação |
|---|---|
| Listagem em tela (dashboard) | GET /user/transactions com paginação. |
| Verificação pontual | GET /user/transactions?clientReference=order-1234. |
| Conciliação diária (< 10k transações) | GET /user/transactions paginado. |
| Conciliação mensal/anual | POST /user/report (CSV assíncrono). |
| BI/Data Warehouse | POST /user/report rodado diariamente, ingestão por ETL. |
O relatório assíncrono gera arquivo CSV com URL assinada de download. Não tem limite de linhas e roda em background. Veja o tutorial de Conciliação.
Armadilhas comuns
| Armadilha | Sintoma |
|---|---|
Pegar tudo sem dateFrom em conta com volume | Resposta lenta, possível timeout |
limit=1000 (acima do permitido) | API rejeita ou trunca |
Iterar até data.length === 0 em vez de hasNextPage | Loop infinito em página vazia da última iteração |
Página fixa (page=1 sempre) | Só lê o primeiro 100, perde o resto |
Passar document com pontuação (123.456.789-00) | Erro 400, regex aceita só dígitos |
Multi-tenant com virtualAccount
Uma conta PayZu só atende várias lojas, filiais ou marcas: marque cada transação com o identificador do tenant e ele volta em todo callback e serve de filtro nas listagens, sem precisar abrir contas separadas.
Dinheiro e precisão
Aqui os valores vêm em reais com centavos, e não em centavos inteiros como em muitos provedores: guarde o dinheiro sem perder precisão, converta só na borda e respeite o mínimo de cada operação.