Skip to main content

​
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

  1. Acesse o Dashboard EconPay
  2. Vá em Configurações > Webhooks
  3. Adicione sua URL (ex: https://seusite.com.br/webhooks/econpay)
  4. 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