Skip to main content

​
O que são Webhooks?

Webhooks são notificações automáticas que a StylePay envia para sua aplicação quando uma transação PIX muda de status. É como receber um SMS avisando que um pagamento foi confirmado.
Em resumo: Você informa uma URL do seu site, e a StylePay manda uma mensagem para essa URL sempre que algo importante acontecer.

​
Passo 1: Configure sua URL

Ao criar uma transação, informe onde quer receber as notificações: 
{
  "amount": 100.50,
  "external_id": "pedido_123",
  "postbackUrl": "https://seusite.com/webhook",
  ...
}
Você pode usar a mesma URL para todos os tipos de notificação.

​
Passo 2: Entenda os Eventos

A StylePay envia 3 tipos principais de notificação:

Recebimento

Quando alguém paga seu QR Code

Pagamento

Quando seu pagamento é processado

Estorno

Quando um recebimento é devolvido

​
Passo 3: Receba as Notificações

​
📥 Recebimento Confirmado

Quando alguém paga seu QR Code: 
{
  "event": "pix.cashin.paid",
  "requestNumber": "pedido_123",
  "statusTransaction": "PAID",
  "idTransaction": "uuid-da-transacao",
  "value": 100.50,
  "debtorName": "João Silva",
  "date": "2025-01-01T10:00:00.000Z"
}
Campos importantes:
  • event: Sempre será pix.cashin.paid para recebimentos
  • requestNumber: Seu código de pedido
  • value: Quanto você recebeu
  • debtorName: Nome de quem pagou

​
📤 Pagamento Realizado

Quando seu pagamento é concluído: 
{
  "event": "pix.cashout.paid",
  "idTransaction": "uuid-da-transacao",
  "statusTransaction": "PAID",
  "value": 50.00,
  "date": "2025-01-01T11:00:00.000Z"
}

​
❌ Pagamento Cancelado

Quando seu pagamento falha: 
{
  "event": "pix.cashout.cancelled",
  "idTransaction": "uuid-da-transacao",
  "statusTransaction": "CANCELLED",
  "value": 50.00,
  "message": "NOT_PAID"
}

​
🔄 Estorno de Recebimento

Quando um pagamento que você recebeu é devolvido: 
{
  "event": "pix.refund.paid_out",
  "requestNumber": "pedido_123",
  "statusTransaction": "CANCELLED",
  "value": 100.50
}

​
Passo 4: Crie seu Endpoint

Seu site precisa ter uma página que receba essas notificações. Aqui está um exemplo simples: 
// Usando Express.js
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const { event, value, requestNumber } = req.body;
  
  // Identificar o tipo de evento
  if (event === 'pix.cashin.paid') {
    console.log(`✅ Recebido: R$ ${value} - Pedido: ${requestNumber}`);
    // Atualizar seu banco de dados aqui
  }
  
  if (event === 'pix.cashout.paid') {
    console.log(`✅ Pagamento enviado: R$ ${value}`);
  }
  
  if (event === 'pix.cashout.cancelled') {
    console.log(`❌ Pagamento cancelado: R$ ${value}`);
  }
  
  // IMPORTANTE: Sempre responda com sucesso
  res.json({ ok: true });
});

app.listen(3000);

​
5 Regras Importantes

1

Sempre responda rapidamente

Retorne status 200 em menos de 5 segundos. Se precisar fazer algo demorado, faça depois de responder.
// ✅ Certo
res.json({ ok: true }); // Responde primeiro
atualizarBancoDeDados(); // Faz depois

// ❌ Errado
atualizarBancoDeDados(); // Demora muito
res.json({ ok: true }); // Responde depois
2

Evite processar duas vezes

Guarde o idTransaction para não processar a mesma notificação mais de uma vez.
// Verificar se já processou
if (jaProcessei(idTransaction)) {
  return res.json({ ok: true });
}
3

Use HTTPS

Sua URL precisa começar com https:// (não http://)
4

Verifique o evento

Sempre confira o campo event antes de processar
if (event === 'pix.cashin.paid') {
  // Processar recebimento
}
5

Salve tudo

Guarde um registro de todas as notificações recebidas para consultar depois

​
Testando em Casa

Para testar enquanto desenvolve:
1

Instale o ngrok

Baixe em: https://ngrok.com/download
2

Execute seu servidor

node seu-servidor.js
3

Abra um túnel

ngrok http 3000
4

Use a URL gerada

https://abc123.ngrok.io/webhook
Cole essa URL no postbackUrl ou callbackUrl

​
Exemplo Completo

Aqui está um exemplo completo e funcional: 
const express = require('express');
const app = express();

app.use(express.json());

// Simulação de banco de dados
const processados = new Set();

app.post('/webhook', async (req, res) => {
  const { event, idTransaction, value, requestNumber, statusTransaction } = req.body;
  
  console.log('📩 Webhook recebido:', event);
  
  // 1. Evitar processar duas vezes
  if (processados.has(idTransaction)) {
    console.log('⚠️  Já processado anteriormente');
    return res.json({ ok: true });
  }
  
  // 2. Responder rapidamente
  res.json({ ok: true });
  
  // 3. Processar o webhook
  try {
    if (event === 'pix.cashin.paid') {
      console.log(`✅ Pagamento recebido!`);
      console.log(`   Valor: R$ ${value}`);
      console.log(`   Pedido: ${requestNumber}`);
      
      // Atualizar pedido no banco de dados
      // await db.pedidos.update(requestNumber, { status: 'pago' });
    }
    
    if (event === 'pix.cashout.paid') {
      console.log(`✅ Pagamento enviado com sucesso!`);
      console.log(`   Valor: R$ ${value}`);
      
      // Atualizar transação no banco de dados
      // await db.transacoes.update(idTransaction, { status: 'concluido' });
    }
    
    if (event === 'pix.cashout.cancelled') {
      console.log(`❌ Pagamento cancelado`);
      console.log(`   Valor: R$ ${value}`);
      
      // Marcar como cancelado
      // await db.transacoes.update(idTransaction, { status: 'cancelado' });
    }
    
    if (event === 'pix.refund.paid_out') {
      console.log(`🔄 Estorno processado`);
      console.log(`   Valor: R$ ${value}`);
      console.log(`   Pedido: ${requestNumber}`);
      
      // Processar estorno
      // await db.pedidos.update(requestNumber, { status: 'estornado' });
    }
    
    // Marcar como processado
    processados.add(idTransaction);
    
  } catch (error) {
    console.error('❌ Erro ao processar:', error);
  }
});

app.listen(3000, () => {
  console.log('🚀 Servidor rodando na porta 3000');
  console.log('📍 Webhook: http://localhost:3000/webhook');
});

​
Dúvidas Frequentes

Não é obrigatório, mas é recomendado. Você pode adicionar um token secreto na URL ou verificar um header específico.
A StylePay tentará reenviar a notificação algumas vezes. Por isso é importante ter um servidor estável.
Sim! Você usa o campo event para saber que tipo de notificação recebeu.
Você pode consultar o status da transação pela API usando o idTransaction se precisar confirmar.
Não. Basta retornar status HTTP 200. O conteúdo da resposta não importa.

​
Precisa de Ajuda?

Suporte Técnico

suporte@stylepay.com.br

WhatsApp

+55 11 9999-9999