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

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: 123,
    reason: 'Solicitação do cliente'
  })
});

const refund = await response.json();

if (refund.success) {
  console.log('Reembolso processado:', refund.transaction.order_number);
  console.log('Valor estornado:', refund.transaction.refund_amount / 100);
}

import requests

response = requests.post(
    'https://api.econpay.com.br/payments/reversal',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'transaction_id': 123,
        'reason': 'Solicitação do cliente'
    }
)

refund = response.json()

if refund['success']:
    print(f"Reembolso processado: {refund['transaction']['order_number']}")
    print(f"Valor: R$ {refund['transaction']['refund_amount'] / 100:.2f}")

<?php
$ch = curl_init('https://api.econpay.com.br/payments/reversal');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'transaction_id' => 123,
    'reason' => 'Solicitação do cliente'
]));

$response = curl_exec($ch);
$refund = json_decode($response, true);

if ($refund['success']) {
    echo 'Reembolso processado: ' . $refund['transaction']['order_number'];
}

curl_close($ch);
?>

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

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Apenas transações com status APPROVED podem ser estornadas. Status atual: PENDING"
}

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

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Esta transação já foi estornada"
}

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

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: 123,
    reason: 'Solicitação do cliente'
  })
});

const refund = await response.json();

if (refund.success) {
  console.log('Reembolso processado:', refund.transaction.order_number);
  console.log('Valor estornado:', refund.transaction.refund_amount / 100);
}

import requests

response = requests.post(
    'https://api.econpay.com.br/payments/reversal',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'transaction_id': 123,
        'reason': 'Solicitação do cliente'
    }
)

refund = response.json()

if refund['success']:
    print(f"Reembolso processado: {refund['transaction']['order_number']}")
    print(f"Valor: R$ {refund['transaction']['refund_amount'] / 100:.2f}")

<?php
$ch = curl_init('https://api.econpay.com.br/payments/reversal');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'transaction_id' => 123,
    'reason' => 'Solicitação do cliente'
]));

$response = curl_exec($ch);
$refund = json_decode($response, true);

if ($refund['success']) {
    echo 'Reembolso processado: ' . $refund['transaction']['order_number'];
}

curl_close($ch);
?>

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

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Apenas transações com status APPROVED podem ser estornadas. Status atual: PENDING"
}

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

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Esta transação já foi estornada"
}

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

string

required

Bearer token JWT obtido no login

Request Body

number

required

ID da transação a ser estornada

string

Motivo do reembolso (opcional)

Response

boolean

Indica se a operação foi bem-sucedida

string

Mensagem de sucesso ou erro

object

Show properties

number

ID da transação

string

Número do pedido

string

Novo status: REFUNDED

number

Valor original em centavos

number

Valor estornado em centavos

string

Data do estorno (ISO 8601)

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

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: 123,
    reason: 'Solicitação do cliente'
  })
});

const refund = await response.json();

if (refund.success) {
  console.log('Reembolso processado:', refund.transaction.order_number);
  console.log('Valor estornado:', refund.transaction.refund_amount / 100);
}

import requests

response = requests.post(
    'https://api.econpay.com.br/payments/reversal',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'transaction_id': 123,
        'reason': 'Solicitação do cliente'
    }
)

refund = response.json()

if refund['success']:
    print(f"Reembolso processado: {refund['transaction']['order_number']}")
    print(f"Valor: R$ {refund['transaction']['refund_amount'] / 100:.2f}")

<?php
$ch = curl_init('https://api.econpay.com.br/payments/reversal');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'transaction_id' => 123,
    'reason' => 'Solicitação do cliente'
]));

$response = curl_exec($ch);
$refund = json_decode($response, true);

if ($refund['success']) {
    echo 'Reembolso processado: ' . $refund['transaction']['order_number'];
}

curl_close($ch);
?>

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

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Apenas transações com status APPROVED podem ser estornadas. Status atual: PENDING"
}

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

{
  "success": false,
  "message": "Transação não pode ser estornada",
  "error": "Esta transação já foi estornada"
}

Prazos de Reembolso

O prazo para o cliente receber o reembolso varia por método de pagamento:

Método	Prazo
PIX	Instantâneo (segundos)
Cartão de Crédito	5 a 10 dias úteis
Cartão de Débito	5 a 10 dias úteis
Boleto	5 a 10 dias úteis

Para cartões, o prazo depende da operadora do cartão do cliente.

Regras de Estorno

Quando posso estornar?

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

Estorno parcial

Atualmente, apenas estornos totais são suportados. O valor total da transação será devolvido.

Taxas de estorno

PIX: Sem taxa adicional
Cartão: Taxa da adquirente pode ser cobrada
Boleto: Sem taxa adicional

Consulte seu contrato para detalhes sobre taxas.

Webhook de estorno

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

Autenticação

Pagamentos

Transações

Clientes

Saldos

Webhooks

POST /payments/reversal

Descrição

Headers

Request Body

Response

Prazos de Reembolso

Regras de Estorno

Exemplo Completo

Tratamento de Erros

Próximos Passos

Listar Transações

Detalhes da Transação

Webhooks

Erros

​Descrição

​Headers

​Request Body

​Response

​Prazos de Reembolso

​Regras de Estorno

​Exemplo Completo

​Tratamento de Erros

​Próximos Passos

Listar Transações

Detalhes da Transação

Webhooks

Erros

Descrição

Headers

Request Body

Response

Prazos de Reembolso

Regras de Estorno

Exemplo Completo

Tratamento de Erros

Próximos Passos