Skip to main content
Para mais detalhes sobre o endpoint e a descrição completa de todos os campos do body, consulte a referência do endpoint.

​
Visão Geral

Esta receita mostra como estornar uma cobrança PIX já paga e acompanhar a confirmação do estorno via webhook. O fluxo completo:
  1. Solicitar o estorno (total ou parcial)
  2. Receber a confirmação via webhook REFUND

​
Pré-requisitos

​
1. Solicitar o estorno

​
Estorno total

Omita o campo value para estornar o valor integral da cobrança: 
curl -X POST 'https://app.plowf.com/api/v1/payments/770e8400-e29b-41d4-a716-446655440000/refund' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json'

​
Estorno parcial

Informe value para estornar apenas parte do valor: 
curl -X POST 'https://app.plowf.com/api/v1/payments/770e8400-e29b-41d4-a716-446655440000/refund' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 100.00
  }'
A resposta confirma que o estorno foi iniciado com status PROCESSING: 
{
  "message": "Reembolso iniciado",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "value": 247.99,
    "fees": 0.5,
    "origin": {
        "uuid": "880e8400-e29b-41d4-a716-446655440001",
        "value": 247.99,
        "fees": 0.5,
    },
    "origin_type": "PAYMENT",
    "refund": {
      "status": "PROCESSING",
      "value": 100.00,
      "pix_original": {
        "end_to_end": "E6070119020240101100500000000001"
      }
    }
  }
}
Após um estorno parcial, o status da cobrança será PARTIALLY_REFUNDED. Após um estorno total, o status será REFUNDED. Você pode realizar múltiplos estornos parciais enquanto houver saldo disponível.

​
2. Receber a confirmação via webhook

Quando o estorno for processado, a Plowf envia um evento REFUND para seu endpoint. Configure-o para escutar esse evento: 
app.post('/webhooks/plowf', (req, res) => {
  // Valide a assinatura HMAC antes de processar
  const { event, data } = req.body;

  if (event === 'REFUND') {
    const refundStatus = data.refund.status;

    if (refundStatus === 'SETTLED') {
      // Estorno liquidado — atualize seu sistema
      console.log('Estorno confirmado para cobrança:', data.uuid);
    } else if (refundStatus === 'FAILED') {
      // Estorno falhou — notifique sua equipe ou tente novamente
      console.log('Estorno falhou para cobrança:', data.uuid);
    }
  }

  res.status(200).json({ received: true });
});
Consulte a página de validação de assinatura para ver como validar a assinatura HMAC.

​
Status possíveis do estorno

StatusSignificado
PROCESSINGEstorno em processamento
SETTLEDEstorno liquidado com sucesso
FAILEDEstorno falhou
CANCELLEDEstorno cancelado

​
Boas práticas

  • Idempotência: Use o uuid da cobrança para evitar processar o mesmo evento REFUND mais de uma vez.
  • Resposta rápida: Responda 200 imediatamente e processe o evento de forma assíncrona se necessário.
  • Nunca confie sem validar: Sempre verifique a assinatura HMAC antes de atualizar seu sistema.

​
Referências