PayZu PaymentsCobranças
Devolver um Pix
Devolva ao comprador o valor inteiro de um Pix pago pela rota PUT /v1/charges/{id}/reverse, a mesma do estorno no cartão.
Peça a devolução
- Cobrança: o
{id}é oidda cobrança Pix. A rota não recebe corpo. - Valor: não envie
amount. O Pix não tem devolução parcial, e o comprador recebe o valor inteiro de volta. - Taxa: a taxa de Pix não é devolvida.
bash
curl --request PUT \
--url 'https://api.sandbox.payzu.dev/v1/charges/0b9c4e2a-6f1d-4c8e-9a37-2d5e8f1a4b6c/reverse' \
--header "Authorization: Bearer $PAYZU_TOKEN" \
--cert "$PAYZU_CLIENT_CERT" --key "$PAYZU_CLIENT_KEY"Trecho da resposta
{
"pixPayment": {
"status": "paid",
"refunds": [
{
"id": "019a6b7c-3d2e-7f10-8a4b-5c6d7e8f9a01",
"amount": 10000,
"status": "requested",
"createdAt": "2026-06-13T09:20:31.000Z",
"confirmedAt": null,
"failedAt": null
}
]
}
}Referência: Estornar ou devolver uma cobrança
A resposta traz a cobrança inteira, com a devolução em pixPayment.refunds. O pixPayment.status continua paid até a conclusão.
| Saldo | Como funciona |
|---|---|
| Débito | O valor inteiro é debitado do saldo disponível no momento do pedido. O recebível do Pix segue para a liquidação normalmente. |
| Condição | O saldo disponível mais o pendente precisam cobrir o valor da devolução menos a taxa. |
| Saldo negativo | O disponível pode ficar negativo, até o valor da devolução se o pendente cobrir. A soma do disponível com o pendente fica negativa no máximo pelo valor da taxa. |
A API não devolve nem cancela um Pix pendente.
Ele é cancelado depois do pixPayment.expiresAt.
Confirme a devolução
| Resultado | Item em refunds | pixPayment.status | O que acontece |
|---|---|---|---|
| Confirmada | confirmed | refunded | O postback é enviado. |
| Não concluída | failed | paid | O valor volta para o seu saldo, você recebe um postback e pode pedir a devolução de novo. |
pixPayment com a devolução concluída
{
"status": "refunded",
"qrCode": "00020101021226800014br.gov.bcb.pix2558pix.example.com/qr/v2/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865802BR5912LOJA EXEMPLO6009SAO PAULO62070503***6304D233",
"expiresAt": "2026-06-12T17:02:10.000Z",
"paidAt": "2026-06-12T16:05:38.000Z",
"canceledAt": null,
"endToEndId": "E00000000202606121605a1B2c3D4e5F",
"refunds": [
{
"id": "019a6b7c-3d2e-7f10-8a4b-5c6d7e8f9a01",
"amount": 10000,
"status": "confirmed",
"createdAt": "2026-06-13T09:20:31.000Z",
"confirmedAt": "2026-06-13T09:21:04.000Z",
"failedAt": null
}
]
}| Campo | Descrição |
|---|---|
id | Identificador da devolução. |
amount | Valor devolvido, em centavos. |
status | requested (pedida), confirmed (concluída) ou failed (não concluída). |
createdAt | Data do pedido. |
confirmedAt | Data da conclusão, ou null. |
failedAt | Data em que a devolução foi dada como não concluída, ou null. |
O postback da devolução não concluída chega com o mesmo pixPayment.status do anterior.
Para distinguir os postbacks, use também o status da última devolução. Veja Status do Pix.
A consulta em Consultar uma cobrança mostra os mesmos campos.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ404 | 400 | Valor do estorno excede o saldo disponível |
PZ403 | 403 | Estorno parcial não disponível |
PZ100 | 404 | Cobrança não encontrada |
PZ308 | 409 | Já existe uma devolução em andamento para este lojista |
PZ402 | 409 | Já existe um estorno em andamento para esta cobrança |
PZ104 | 422 | Conta sem provedor de pagamento configurado |
PZ108 | 422 | Configuração de pagamento da conta incompleta |
PZ302 | 422 | O Pix ainda não foi pago |
PZ303 | 422 | Devolução do Pix já solicitada |
PZ304 | 422 | Não foi possível devolver este Pix agora. Tente novamente mais tarde. |
PZ305 | 422 | Não foi possível devolver o Pix |
PZ400 | 422 | Cobrança não disponível para estorno |
PZ800 | 422 | Conta sem carteira configurada |
PZ900 | 422 | O provedor de pagamento recusou a operação |
PZ901 | 503 | Não foi possível estabelecer comunicação com o provedor de pagamento. Tente novamente em instantes. |
Os erros de autenticação e de validação e os demais códigos estão no Catálogo de erros.