Skip to main content
POST
/
payments
/
reversal
curl --request POST \
  --url https://api.econpay.com.br/payments/reversal \
  --header 'Authorization: Bearer SEU_TOKEN_JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": 123,
    "reason": "Solicitação do cliente"
  }'

{
  "success": true,
  "message": "Reembolso processado com sucesso",
  "transaction": {
    "id": 123,
    "order_number": "ORD-20240122-123456",
    "status": "REFUNDED",
    "amount": 10000,
    "refund_amount": 10000,
    "payment_type": "pix",
    "refunded_at": "2024-01-22T15:00:00Z",
    "created_at": "2024-01-22T10:30:00Z"
  }
}

​
Descrição

Processa o reembolso total de uma transação aprovada. O valor será devolvido ao cliente de acordo com o método de pagamento original.
Apenas transações com status APPROVED podem ser estornadas.

​
Headers

​
Authorization
string
required
Bearer token JWT obtido no login

​
Request Body

​
transaction_id
number
required
ID da transação a ser estornada
​
reason
string
Motivo do reembolso (opcional)

​
Response

​
success
boolean
Indica se a operação foi bem-sucedida
​
message
string
Mensagem de sucesso ou erro
​
transaction
object
curl --request POST \
  --url https://api.econpay.com.br/payments/reversal \
  --header 'Authorization: Bearer SEU_TOKEN_JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": 123,
    "reason": "Solicitação do cliente"
  }'

{
  "success": true,
  "message": "Reembolso processado com sucesso",
  "transaction": {
    "id": 123,
    "order_number": "ORD-20240122-123456",
    "status": "REFUNDED",
    "amount": 10000,
    "refund_amount": 10000,
    "payment_type": "pix",
    "refunded_at": "2024-01-22T15:00:00Z",
    "created_at": "2024-01-22T10:30:00Z"
  }
}

​
Prazos de Reembolso

O prazo para o cliente receber o reembolso varia por método de pagamento:
MétodoPrazo
PIXInstantâneo (segundos)
Cartão de Crédito5 a 10 dias úteis
Cartão de Débito5 a 10 dias úteis
Boleto5 a 10 dias úteis
Para cartões, o prazo depende da operadora do cartão do cliente.

​
Regras de Estorno

  • Apenas transações com status APPROVED
  • Não há limite de tempo (pode estornar meses depois)
  • Cada transação pode ser estornada apenas uma vez
Atualmente, apenas estornos totais são suportados. O valor total da transação será devolvido.
  • PIX: Sem taxa adicional
  • Cartão: Taxa da adquirente pode ser cobrada
  • Boleto: Sem taxa adicional
Consulte seu contrato para detalhes sobre taxas.
Quando um estorno é processado, um webhook payment.refunded é enviado:
{
  "event": "payment.refunded",
  "transaction_id": 123,
  "status": "REFUNDED",
  "refund_amount": 10000,
  "refunded_at": "2024-01-22T15:00:00Z"
}

​
Exemplo Completo

async function refundPayment(transactionId, reason) {
  try {
    // 1. Buscar detalhes da transação
    const transaction = await fetch(
      `https://api.econpay.com.br/transactions/${transactionId}`,
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    ).then(r => r.json());
    
    // 2. Verificar se pode ser estornada
    if (transaction.status !== 'APPROVED') {
      throw new Error(`Transação não pode ser estornada. Status: ${transaction.status}`);
    }
    
    // 3. Processar estorno
    const refund = await fetch('https://api.econpay.com.br/payments/reversal', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        transaction_id: transactionId,
        reason: reason
      })
    }).then(r => r.json());
    
    if (refund.success) {
      console.log('✅ Reembolso processado com sucesso');
      console.log(`Pedido: ${refund.transaction.order_number}`);
      console.log(`Valor: R$ ${refund.transaction.refund_amount / 100}`);
      
      // 4. Notificar cliente
      await sendRefundEmail(transaction.customer.email, refund);
      
      return refund;
    } else {
      throw new Error(refund.error);
    }
  } catch (error) {
    console.error('❌ Erro ao processar reembolso:', error.message);
    throw error;
  }
}

// Uso
await refundPayment(123, 'Produto com defeito');

​
Tratamento de Erros

async function safeRefund(transactionId, reason) {
  try {
    const response = await fetch('https://api.econpay.com.br/payments/reversal', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ transaction_id: transactionId, reason })
    });
    
    const data = await response.json();
    
    if (!response.ok) {
      switch (response.status) {
        case 400:
          if (data.error.includes('já foi estornada')) {
            console.log('Transação já estornada anteriormente');
            return { alreadyRefunded: true };
          }
          throw new Error(`Não pode estornar: ${data.error}`);
        
        case 404:
          throw new Error('Transação não encontrada');
        
        default:
          throw new Error(data.error || 'Erro desconhecido');
      }
    }
    
    return data;
  } catch (error) {
    console.error('Erro ao estornar:', error.message);
    throw error;
  }
}

​
Próximos Passos

Listar Transações

Consultar transações para estornar

Detalhes da Transação

Ver informações completas

Webhooks

Receber notificações de estorno

Erros

Códigos de erro