Webhooks Overview

Eventos Disponíveis

A EconPay envia webhooks para notificar sobre mudanças de status em tempo real. Configure sua URL no dashboard para receber notificações.

Guia Completo de Webhooks

Veja o guia completo com exemplos de implementação

Eventos

payment.approved

Enviado quando um pagamento é aprovado.

{
  "event": "payment.approved",
  "transaction_id": 123,
  "order_number": "ORD-20240122-123456",
  "status": "APPROVED",
  "amount": 10000,
  "payment_type": "pix",
  "customer": {
    "name": "João da Silva",
    "email": "[email protected]",
    "document": "12345678900"
  },
  "paid_at": "2024-01-22T10:35:00Z",
  "created_at": "2024-01-22T10:30:00Z"
}

payment.failed

Enviado quando um pagamento falha ou é recusado.

{
  "event": "payment.failed",
  "transaction_id": 124,
  "order_number": "ORD-20240122-123457",
  "status": "FAILED",
  "amount": 15000,
  "payment_type": "credit",
  "failure_reason": "Cartão recusado pela operadora",
  "customer": {
    "name": "Maria Santos",
    "email": "[email protected]",
    "document": "98765432100"
  },
  "failed_at": "2024-01-22T11:00:00Z",
  "created_at": "2024-01-22T10:59:00Z"
}

payment.refunded

Enviado quando um reembolso é processado.

{
  "event": "payment.refunded",
  "transaction_id": 123,
  "order_number": "ORD-20240122-123456",
  "status": "REFUNDED",
  "amount": 10000,
  "refund_amount": 10000,
  "payment_type": "pix",
  "refund_reason": "Solicitação do cliente",
  "customer": {
    "name": "João da Silva",
    "email": "[email protected]",
    "document": "12345678900"
  },
  "refunded_at": "2024-01-22T15:00:00Z",
  "created_at": "2024-01-22T10:30:00Z"
}

Configuração

Acesse o Dashboard EconPay
Vá em Configurações > Webhooks
Adicione sua URL (ex: https://seusite.com.br/webhooks/econpay)
Salve

Implementação Básica

Node.js/Express

app.post('/webhooks/econpay', express.json(), (req, res) => {
  const event = req.body;
  
  console.log('Webhook recebido:', event.event);
  
  switch (event.event) {
    case 'payment.approved':
      // Marcar pedido como pago
      markOrderAsPaid(event.order_number);
      break;
      
    case 'payment.failed':
      // Notificar cliente sobre falha
      notifyPaymentFailed(event.customer.email);
      break;
      
    case 'payment.refunded':
      // Processar estorno
      processRefund(event.order_number);
      break;
  }
  
  // IMPORTANTE: Retornar 200 OK
  res.status(200).json({ received: true });
});

Retry e Timeout

Timeout: 30 segundos
Retries: 3 tentativas
Intervalo: 1 minuto entre tentativas

Seu endpoint deve responder com status 200 em menos de 30 segundos.

Segurança

Sempre valide que o webhook veio da EconPay:

// Consultar API para confirmar
const transaction = await fetch(
  `https://api.econpay.com.br/transactions/${event.transaction_id}`,
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
).then(r => r.json());

if (transaction.status !== event.status) {
  console.warn('Status divergente no webhook');
  return;
}

Testando

Use ngrok para testar webhooks localmente:

# Expor porta 3000
ngrok http 3000

# Usar URL gerada no dashboard
https://abc123.ngrok.io/webhooks/econpay

Próximos Passos

Guia Completo

Implementação detalhada

Criar Pagamento

Processar pagamentos

Listar Transações

Consultar histórico

Erros

Códigos de erro

Autenticação

Pagamentos

Transações

Clientes

Saldos

Webhooks

Eventos Disponíveis

Guia Completo de Webhooks

Eventos

payment.approved

payment.failed

payment.refunded

Configuração

Implementação Básica

Retry e Timeout

Segurança

Testando

Próximos Passos

Guia Completo

Criar Pagamento

Listar Transações

Erros

​Eventos Disponíveis

Guia Completo de Webhooks

​Eventos

​payment.approved

​payment.failed

​payment.refunded

​Configuração

​Implementação Básica

​Retry e Timeout

​Segurança

​Testando

​Próximos Passos

Guia Completo

Criar Pagamento

Listar Transações

Erros

Eventos Disponíveis

Eventos

payment.approved

payment.failed

payment.refunded

Configuração

Implementação Básica

Retry e Timeout

Segurança

Testando

Próximos Passos