PayZu PaymentsCobranças

Devolver um Pix


Nesta páginaPeça a devoluçãoConfirme a devoluçãoErros desta operação

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} é o id da 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.

SaldoComo funciona
DébitoO valor inteiro é debitado do saldo disponível no momento do pedido. O recebível do Pix segue para a liquidação normalmente.
CondiçãoO saldo disponível mais o pendente precisam cobrir o valor da devolução menos a taxa.
Saldo negativoO 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

ResultadoItem em refundspixPayment.statusO que acontece
ConfirmadaconfirmedrefundedO postback é enviado.
Não concluídafailedpaidO 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
    }
  ]
}
CampoDescrição
idIdentificador da devolução.
amountValor devolvido, em centavos.
statusrequested (pedida), confirmed (concluída) ou failed (não concluída).
createdAtData do pedido.
confirmedAtData da conclusão, ou null.
failedAtData 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ódigoHTTPMensagem
PZ404400Valor do estorno excede o saldo disponível
PZ403403Estorno parcial não disponível
PZ100404Cobrança não encontrada
PZ308409Já existe uma devolução em andamento para este lojista
PZ402409Já existe um estorno em andamento para esta cobrança
PZ104422Conta sem provedor de pagamento configurado
PZ108422Configuração de pagamento da conta incompleta
PZ302422O Pix ainda não foi pago
PZ303422Devolução do Pix já solicitada
PZ304422Não foi possível devolver este Pix agora. Tente novamente mais tarde.
PZ305422Não foi possível devolver o Pix
PZ400422Cobrança não disponível para estorno
PZ800422Conta sem carteira configurada
PZ900422O provedor de pagamento recusou a operação
PZ901503Nã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.