Cenários práticos
Várias lojas numa conta
Uma rede recebe os Pix de todas as lojas numa única conta e marca cada cobrança com o código da loja em virtualAccount.
| O que muda | Valor |
|---|---|
virtualAccount em POST /pix | Código da loja, o mesmo em todas as cobranças dela |
clientReference | Único na conta; inclua o código da loja |
GET /pix com virtualAccount | Retorna uma cobrança só, a mais recente da loja |
GET /user/transactions com virtualAccount | Lista as transações da loja, com paginação |
{
"amount": 89.9,
"clientReference": "loja-centro-01:pedido-4821",
"virtualAccount": "loja-centro-01",
"expiresIn": 900,
"callbackUrl": "https://sualoja.com.br/webhook"
}virtualAccount volta no corpo de cada aviso dessa cobrança. Para listar as vendas de uma loja:
curl "https://pix.sandbox.payzu.dev/v1/user/transactions?virtualAccount=loja-centro-01&dateFrom=2026-08-01T00:00:00-03:00&dateTo=2026-08-31T23:59:59-03:00&limit=100" \
-H "Authorization: Bearer SEU_TOKEN"A referência é única na conta, não por loja.
Se as lojas A e B usarem pedido-42 como referência, a segunda chamada retorna a cobrança da primeira.
Cobrança que expira
Um pedido reserva estoque por 15 minutos. Se o pagador não pagar nesse prazo, a cobrança precisa expirar e o estoque voltar.
| O que muda | Valor |
|---|---|
expiresIn em POST /pix | Segundos até expirar, de 60 a 172.000 |
| Status depois do prazo | EXPIRED quando a instituição confirma o vencimento; só então chega TRANSACTION_EXPIRED |
| Nova tentativa do cliente | Nova cobrança, com clientReference novo |
{
"amount": 150,
"clientReference": "pedido-4822",
"expiresIn": 900,
"callbackUrl": "https://sualoja.com.br/webhook"
}Não espere o aviso para liberar o estoque.
No fim do prazo, consulte GET /pix com o clientReference e, se a cobrança não estiver COMPLETED, reponha o item no estoque. O evento está em Transação expirada.
Repetir o clientReference de uma cobrança expirada retorna a cobrança expirada.
Para a nova tentativa do cliente, crie outra cobrança, com referência nova.
Devolução parcial
O cliente pagou R$ 100,00 e devolveu um item de R$ 30,50.
| O que muda | Valor |
|---|---|
amount em POST /refund/{transactionId} | Valor a devolver, maior que zero; sem ele, a devolução é total |
clientReference | Sua chave de idempotência da devolução |
| Resposta | status: COMPLETED e refundStatus: PENDING |
| Conclusão | Chega pelo callbackUrl da cobrança e aos webhooks, como TRANSACTION_REFUNDED, com status: COMPLETED enquanto a soma devolvida não alcança o valor recebido |
| Soma devolvida | refundAmount acumula cada parcial; no aviso, chega como texto |
{
"amount": 30.5,
"description": "Devolução pedida pelo cliente",
"clientReference": "refund-2026-0001"
}| Erro | Quando acontece |
|---|---|
400 com PZC611 | amount passa do que ainda pode ser devolvido. |
409 com PZC221 | A transação já foi devolvida por inteiro. |
Os prazos e os estados estão em Devolver um Pix recebido.
A transação continua COMPLETED enquanto a soma devolvida não alcança o valor recebido.
refundAmount e refundStatus são atualizados. O evento TRANSACTION_REFUNDED sai a cada devolução concluída: com status: COMPLETED até a soma alcançar o valor recebido e com REFUNDED quando alcança.