Marcar fatura como estornada

Marca uma Invoice `PAID` como `REFUNDED` (total ou parcial). Esse endpoint **apenas atualiza o status** — o estorno PIX em si é executado em outro fluxo (módulo de Refund). Use após confirmar com seu time que o PIX bancário foi feito. `refundedAmount` em centavos, deve ser `> 0` e `<= amountPaid`.

POST/v2/invoices/:id/mark-refunded

Não executa o PIX

refundedAmount Este endpoint só altera o status da Invoice no sistema. O estorno PIX bancário é responsabilidade do módulo de Refund — chame-o separadamente. Esse aqui é o registro contábil do que já foi estornado.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

idstring (path, UUID)obrigatório

UUID da Invoice.

Exemplo: inv_111aaa

Body da requisição

Content-Type: application/json

JSON

{
  "refundedAmount": 3000
}

Respostas

200

Invoice marcada como REFUNDED. refundedAmount em centavos. amountPaid permanece como estava (o que o cliente pagou).

JSON

{
  "id": "inv_111aaa",
  "status": "REFUNDED",
  "amount": 10000,
  "amountPaid": 10000,
  "refundedAmount": 3000,
  "refundedAt": "2026-09-15T16:00:00.000Z",
  "updatedAt": "2026-09-15T16:00:00.000Z"
}

400

Causas: Invoice não está PAID, refundedAmount <= 0 ou > amountPaid.

JSON

{
  "status": 400,
  "error": "refundedAmount nao pode ser maior que amountPaid"
}

404

Invoice não encontrada.

JSON

{ "status": 404, "error": "Invoice nao encontrada" }

Exemplos

cURL

# Estorno parcial de R$ 30,00 em uma invoice de R$ 100,00:
curl -X POST "https://api.pagnovo.com/v2/invoices/inv_111aaa/mark-refunded" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "refundedAmount": 3000 }'