Skip to main content
POST
/
payments
/
pix
/
refund
curl --request POST \
  --url https://api.econpay.com.br/payments/pix/refund \
  --header 'Authorization: Bearer SEU_TOKEN_JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": 123,
    "description": "Cancelamento da compra"
  }'

{
  "success": true,
  "message": "Estorno PIX processado com sucesso",
  "transaction": {
    "id": 123,
    "payment_id": "860958c4-adf8-438d-8ee6-eff6cf20ed05",
    "status": 6,
    "amount": 10000,
    "refunded_amount": 10000,
    "refunded_at": "2024-01-15T10:30:00Z"
  }
}

​
Descrição

Processa 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.
Requisitos para Estorno:
  • Transação deve estar com status PAID (paga)
  • Prazo máximo de 90 dias após o pagamento
  • Conta deve ter saldo suficiente para o estorno
  • Valor do estorno não pode exceder o valor original

​
Headers

​
Authorization
string
required
Bearer token JWT obtido no login

​
Request Body

​
transaction_id
number
required
ID da transação PIX a ser estornada (ID interno do sistema)
​
amount
number
Valor a ser estornado em reais (opcional - se não informado, estorna valor total)Exemplo: 50.00 para estornar R$ 50,00
​
description
string
Descrição do motivo do estorno (opcional)Exemplo: “Cancelamento da compra”

​
Response

​
success
boolean
Indica se o estorno foi processado com sucesso
​
message
string
Mensagem de retorno
​
transaction
object
curl --request POST \
  --url https://api.econpay.com.br/payments/pix/refund \
  --header 'Authorization: Bearer SEU_TOKEN_JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": 123,
    "description": "Cancelamento da compra"
  }'

{
  "success": true,
  "message": "Estorno PIX processado com sucesso",
  "transaction": {
    "id": 123,
    "payment_id": "860958c4-adf8-438d-8ee6-eff6cf20ed05",
    "status": 6,
    "amount": 10000,
    "refunded_amount": 10000,
    "refunded_at": "2024-01-15T10:30:00Z"
  }
}

​
Tipos de Estorno

​
Estorno Total

Estorna 100% do valor da transação PIX.Como usar:
  • Não enviar o campo amount no body
  • Ou enviar amount igual ao valor original
Quando usar:
  • Cancelamento completo da compra
  • Devolução total do valor pago
Exemplo:
{
  "transaction_id": 123,
  "description": "Cancelamento da compra"
}

​
Critérios de Elegibilidade

Para que uma transação PIX possa ser estornada, ela deve atender aos seguintes critérios:
A transação deve estar com status PAID (paga). Transações pendentes, canceladas ou já estornadas não podem ser estornadas.
O estorno deve ser solicitado em até 90 dias após o pagamento original. Após esse prazo, o estorno não será processado.
A conta deve ter saldo suficiente para processar o estorno. O valor será debitado da sua conta e creditado na conta do pagador.
O valor do estorno (ou soma de estornos parciais) não pode exceder o valor original da transação.

​
Fluxo do Estorno

1

Validação

Sistema valida se a transação pode ser estornada (status, prazo, saldo)
2

Processamento

Estorno é enviado para a Firebank e processado
3

Atualização

Status da transação é atualizado para REFUNDED (6)
4

Crédito

Valor é creditado na conta do pagador (geralmente instantâneo)

​
Códigos de Erro

CódigoDescrição
TRANSACTION_NOT_FOUNDTransação não encontrada
TRANSACTION_NOT_PIXTransação não é do tipo PIX
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

Listar Transações

Consulte histórico de estornos

Erros

Códigos de erro completos