Estornar transação

Estorna uma transação aprovada. Estornos PIX devolvem o valor integral ao pagador imediatamente. Estornos de cartão de crédito são iniciados via adquirente e podem levar até 30 dias úteis para aparecer no extrato do titular.

POST/transactions/refund/:transactionId

Estornos são finais

transactionId Uma vez iniciado, um estorno não pode ser cancelado. Confira o ID da transação e o valor antes de chamar isso em produção. Considere adicionar um passo de confirmação na sua ferramenta de estorno.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

transactionIdstring (path)obrigatório

ID interno da transação a estornar. Apenas transações com status `APPROVED` podem ser estornadas.

Exemplo: 1234567

Respostas

200

Estorno iniciado.

JSON

{
  "id": 1234567,
  "status": "REFUNDED",
  "refundedAt": "2026-04-08T16:45:21.501Z",
  "message": "Transaction refunded successfully"
}

400

A transação não está em estado estornável (já estornada, nunca aprovada, em chargeback ou marcada como INCOSISTENT).

JSON

{
  "statusCode": 400,
  "message": "Transaction is not in APPROVED status"
}

403

API key sem a permissão createRefund.

JSON

{
  "statusCode": 403,
  "message": "You do not have permission to access this resource"
}

404

Transação não encontrada.

JSON

{ "statusCode": 404, "message": "Transaction not found" }

Exemplos

cURL

curl -X POST "https://api.pagnovo.com/transactions/refund/1234567" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

JavaScript

const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");

const res = await fetch("https://api.pagnovo.com/transactions/refund/1234567", {
  method: "POST",
  headers: { Authorization: `Basic ${token}` },
});

const traceId = res.headers.get("x-trace-id");
const result = await res.json();

if (res.ok) {
  console.log("estornada em:", result.refundedAt);
} else {
  console.error(`falha no estorno: ${result.message} (trace: ${traceId})`);
}