Pular para o conteúdo principal
POST
/
pix
/
v2
/
payment
/
refund
/
{id}
Estornar Transação PIX
curl --request POST \
  --url https://api-gateway.firebanking.dev/pix/v2/payment/refund/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "value": 1.01,
  "description": "<string>"
}
'
{
  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

​
Visão Geral

Solicite o estorno (refund) de uma transação PIX que foi paga com sucesso. O estorno pode ser total ou parcial e deve ser solicitado em até 90 dias após o pagamento original.
Apenas transações com status PAID podem ser estornadas. Certifique-se de ter saldo suficiente para o estorno.

​
Parâmetros da URL

​
id
string
required
ID da transação PIX a ser estornada

​
Parâmetros do Body

​
value
number
Valor do estorno em reais. Se não informado, será estorno total
​
description
string
Descrição do motivo do estorno

​
Exemplo de Requisição

curl --request POST \
  --url https://api-gateway.firebanking.com.br/pix/v2/payment/refund/<id> \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <sua-chave-api>' \
  --data '{
    "description": "Sua descrição"
  }'

​
Exemplo de Resposta

{
  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

​
Limitações do Estorno

​
Critérios de Elegibilidade

  • Status: Transação deve estar PAID
  • Prazo: Até 90 dias após o pagamento
  • Saldo: Conta deve ter saldo suficiente
  • Valor: Não pode exceder valor original

​
Tipos de Estorno

  • Valor: 100% do valor original
  • Uso: Cancelamento completo da compra
  • Requisição: Sem campo value ou value igual ao original
  • Valor: Parte do valor original
  • Uso: Desconto, devolução parcial
  • Limitação: Soma dos estornos ≤ valor original

​
Códigos de Erro

CódigoDescrição
TRANSACTION_NOT_FOUNDTransação não encontrada
TRANSACTION_NOT_REFUNDABLETransação não pode ser estornada
REFUND_PERIOD_EXPIREDPrazo de estorno expirado (90 dias)
INSUFFICIENT_BALANCESaldo insuficiente para estorno
REFUND_VALUE_EXCEEDS_ORIGINALValor do estorno excede original

​
Próximos Passos

Consultar Transação

Verifique se transação é elegível para estorno

Webhooks

Monitore status dos estornos

Authorizations

​
x-api-key
string
header
required

Chave de API para autenticação

Path Parameters

​
id
string
required

ID da transação PIX a ser estornada

Body

application/json
​
value
number

Valor do estorno em reais. Se não informado, será estorno total

Intervalo obrigatório: x >= 0.01
​
description
string

Descrição do motivo do estorno

Response

Estorno processado com sucesso

​
transactionId
string
required

ID único do estorno

Example:

"75906707-8c31-479c-b354-aa805c4cefbc"