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"
  }'

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": 124,
    "amount": 50.00,
    "description": "Devolução parcial do valor"
  }'

const response = await fetch('https://api.econpay.com.br/payments/pix/refund', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    transaction_id: 123,
    amount: 50.00, // Opcional - omitir para estorno total
    description: 'Cancelamento da compra'
  })
});

const refund = await response.json();

if (refund.success) {
  console.log('Estorno processado:', refund.transaction.id);
  console.log('Valor estornado:', refund.transaction.refunded_amount / 100);
}

import requests

response = requests.post(
    'https://api.econpay.com.br/payments/pix/refund',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'transaction_id': 123,
        'amount': 50.00,  # Opcional
        'description': 'Cancelamento da compra'
    }
)

refund = response.json()

if refund['success']:
    print(f"Estorno processado: {refund['transaction']['id']}")
    print(f"Valor estornado: R$ {refund['transaction']['refunded_amount'] / 100:.2f}")

{
  "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"
  }
}

{
  "success": true,
  "message": "Estorno PIX processado com sucesso",
  "transaction": {
    "id": 124,
    "payment_id": "75906707-8c31-479c-b354-aa805c4cefbc",
    "status": 6,
    "amount": 10000,
    "refunded_amount": 5000,
    "refunded_at": "2024-01-15T10:35:00Z"
  }
}

{
  "success": false,
  "message": "Esta transação não é do tipo PIX",
  "error": "Use o endpoint /payments/reversal para outros tipos de pagamento"
}

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Transação não está com status PAID"
}

{
  "success": false,
  "message": "Transação não encontrada",
  "error": "Nenhuma transação encontrada com ID: 123"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Prazo de estorno expirado (90 dias)"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Saldo insuficiente para estorno"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Valor do estorno excede valor original"
}

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"
  }'

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": 124,
    "amount": 50.00,
    "description": "Devolução parcial do valor"
  }'

const response = await fetch('https://api.econpay.com.br/payments/pix/refund', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    transaction_id: 123,
    amount: 50.00, // Opcional - omitir para estorno total
    description: 'Cancelamento da compra'
  })
});

const refund = await response.json();

if (refund.success) {
  console.log('Estorno processado:', refund.transaction.id);
  console.log('Valor estornado:', refund.transaction.refunded_amount / 100);
}

import requests

response = requests.post(
    'https://api.econpay.com.br/payments/pix/refund',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'transaction_id': 123,
        'amount': 50.00,  # Opcional
        'description': 'Cancelamento da compra'
    }
)

refund = response.json()

if refund['success']:
    print(f"Estorno processado: {refund['transaction']['id']}")
    print(f"Valor estornado: R$ {refund['transaction']['refunded_amount'] / 100:.2f}")

{
  "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"
  }
}

{
  "success": true,
  "message": "Estorno PIX processado com sucesso",
  "transaction": {
    "id": 124,
    "payment_id": "75906707-8c31-479c-b354-aa805c4cefbc",
    "status": 6,
    "amount": 10000,
    "refunded_amount": 5000,
    "refunded_at": "2024-01-15T10:35:00Z"
  }
}

{
  "success": false,
  "message": "Esta transação não é do tipo PIX",
  "error": "Use o endpoint /payments/reversal para outros tipos de pagamento"
}

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Transação não está com status PAID"
}

{
  "success": false,
  "message": "Transação não encontrada",
  "error": "Nenhuma transação encontrada com ID: 123"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Prazo de estorno expirado (90 dias)"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Saldo insuficiente para estorno"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Valor do estorno excede valor original"
}

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

string

required

Bearer token JWT obtido no login

Request Body

number

required

ID da transação PIX a ser estornada (ID interno do sistema)

number

Valor a ser estornado em reais (opcional - se não informado, estorna valor total)Exemplo: 50.00 para estornar R$ 50,00

string

Descrição do motivo do estorno (opcional)Exemplo: “Cancelamento da compra”

Response

boolean

Indica se o estorno foi processado com sucesso

string

Mensagem de retorno

object

Show properties

number

ID da transação

string

ID do pagamento na subadquirente (Firebank)

number

Status da transação (6 = REFUNDED)

number

Valor original da transação em centavos

number

Valor estornado em centavos

string

Data do estorno (ISO 8601)

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"
  }'

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": 124,
    "amount": 50.00,
    "description": "Devolução parcial do valor"
  }'

const response = await fetch('https://api.econpay.com.br/payments/pix/refund', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    transaction_id: 123,
    amount: 50.00, // Opcional - omitir para estorno total
    description: 'Cancelamento da compra'
  })
});

const refund = await response.json();

if (refund.success) {
  console.log('Estorno processado:', refund.transaction.id);
  console.log('Valor estornado:', refund.transaction.refunded_amount / 100);
}

import requests

response = requests.post(
    'https://api.econpay.com.br/payments/pix/refund',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'transaction_id': 123,
        'amount': 50.00,  # Opcional
        'description': 'Cancelamento da compra'
    }
)

refund = response.json()

if refund['success']:
    print(f"Estorno processado: {refund['transaction']['id']}")
    print(f"Valor estornado: R$ {refund['transaction']['refunded_amount'] / 100:.2f}")

{
  "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"
  }
}

{
  "success": true,
  "message": "Estorno PIX processado com sucesso",
  "transaction": {
    "id": 124,
    "payment_id": "75906707-8c31-479c-b354-aa805c4cefbc",
    "status": 6,
    "amount": 10000,
    "refunded_amount": 5000,
    "refunded_at": "2024-01-15T10:35:00Z"
  }
}

{
  "success": false,
  "message": "Esta transação não é do tipo PIX",
  "error": "Use o endpoint /payments/reversal para outros tipos de pagamento"
}

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Transação não está com status PAID"
}

{
  "success": false,
  "message": "Transação não encontrada",
  "error": "Nenhuma transação encontrada com ID: 123"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Prazo de estorno expirado (90 dias)"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Saldo insuficiente para estorno"
}

{
  "success": false,
  "message": "Erro ao processar estorno PIX",
  "error": "Valor do estorno excede valor original"
}

Tipos de Estorno

Estorno Total
Estorno Parcial

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"
}

Estorno Parcial

Estorna apenas parte do valor da transação PIX.Como usar:

Enviar o campo amount com o valor desejado em reais
Valor deve ser menor que o valor original

Quando usar:

Desconto após a compra
Devolução parcial de produtos
Ajuste de valores

Limitações:

Soma de todos os estornos não pode exceder valor original
Múltiplos estornos parciais são permitidos

Exemplo:

{
  "transaction_id": 124,
  "amount": 50.00,
  "description": "Devolução parcial - 1 item"
}

Critérios de Elegibilidade

Para que uma transação PIX possa ser estornada, ela deve atender aos seguintes critérios:

Status da Transação

A transação deve estar com status PAID (paga). Transações pendentes, canceladas ou já estornadas não podem ser estornadas.

Prazo de Estorno

O estorno deve ser solicitado em até 90 dias após o pagamento original. Após esse prazo, o estorno não será processado.

Saldo Disponível

A conta deve ter saldo suficiente para processar o estorno. O valor será debitado da sua conta e creditado na conta do pagador.

Valor do Estorno

O valor do estorno (ou soma de estornos parciais) não pode exceder o valor original da transação.

Fluxo do Estorno

Validação

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

Processamento

Estorno é enviado para a Firebank e processado

Atualização

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

Crédito

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

Códigos de Erro

Código	Descrição
`TRANSACTION_NOT_FOUND`	Transação não encontrada
`TRANSACTION_NOT_PIX`	Transação não é do tipo PIX
`TRANSACTION_NOT_REFUNDABLE`	Transação não pode ser estornada
`REFUND_PERIOD_EXPIRED`	Prazo de estorno expirado (90 dias)
`INSUFFICIENT_BALANCE`	Saldo insuficiente para estorno
`REFUND_VALUE_EXCEEDS_ORIGINAL`	Valor 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

Autenticação

Pagamentos

Transações

Clientes

Saldos

Webhooks

POST /payments/pix/refund

Descrição

Headers

Request Body

Response

Tipos de Estorno

Estorno Total

Estorno Parcial

Critérios de Elegibilidade

Fluxo do Estorno

Códigos de Erro

Próximos Passos

Consultar Transação

Webhooks

Listar Transações

Erros

​Descrição

​Headers

​Request Body

​Response

​Tipos de Estorno

​Estorno Total

​Estorno Parcial

​Critérios de Elegibilidade

​Fluxo do Estorno

​Códigos de Erro

​Próximos Passos

Consultar Transação

Webhooks

Listar Transações

Erros

Descrição

Headers

Request Body

Response

Tipos de Estorno

Estorno Total

Estorno Parcial

Critérios de Elegibilidade

Fluxo do Estorno

Códigos de Erro

Próximos Passos