PayZu PixApoio

Cenários práticos


Nesta páginaVárias lojas numa contaCobrança que expiraDevolução parcial

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 mudaValor
virtualAccount em POST /pixCódigo da loja, o mesmo em todas as cobranças dela
clientReferenceÚnico na conta; inclua o código da loja
GET /pix com virtualAccountRetorna uma cobrança só, a mais recente da loja
GET /user/transactions com virtualAccountLista as transações da loja, com paginação
POST /pix
{
  "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:

bash
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 mudaValor
expiresIn em POST /pixSegundos até expirar, de 60 a 172.000
Status depois do prazoEXPIRED quando a instituição confirma o vencimento; só então chega TRANSACTION_EXPIRED
Nova tentativa do clienteNova cobrança, com clientReference novo
POST /pix
{
  "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 mudaValor
amount em POST /refund/{transactionId}Valor a devolver, maior que zero; sem ele, a devolução é total
clientReferenceSua chave de idempotência da devolução
Respostastatus: COMPLETED e refundStatus: PENDING
ConclusãoChega 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 devolvidarefundAmount acumula cada parcial; no aviso, chega como texto
POST /refund/PAYZU20260810JD4WQ2R7ZB000000
{
  "amount": 30.5,
  "description": "Devolução pedida pelo cliente",
  "clientReference": "refund-2026-0001"
}
ErroQuando acontece
400 com PZC611amount passa do que ainda pode ser devolvido.
409 com PZC221A 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.