Webhooks

Receba notificações automáticas sempre que o status de uma transação mudar

A Velfy Payments notifica sua aplicação em tempo real através de requisições POST para a URL configurada, sempre que o status de uma transação muda.

🔧 Configurando a URL de Destino

Informe a URL para onde deseja receber as notificações no campo postbackUrl, ao criar a transação:

{
  "paymentMethod": "pix",
  "postbackUrl": "https://sualoja.com/webhooks/velfy"
}

Todos os eventos relacionados a essa transação serão enviados para essa URL.

📡 Formato da Notificação

POST {sua postbackUrl}
Content-Type: application/json

{
  "id": 4587123,
  "type": "transaction",
  "url": "https://sualoja.com/webhooks/velfy",
  "data": {
    "id": 918234,
    "status": "paid",
    "amount": 10000,
    "paidAmount": 10000,
    "paidAt": "2026-07-28T12:05:00.000Z",
    "paymentMethod": "pix",
    "externalRef": "pedido-123",
    "secureId": "9c1a9b2e-7c3d-4e11-9a2f-3a1c5f0e9d21",
    "fee": {
      "netAmount": 9700,
      "fixedAmount": 300,
      "estimatedFee": 300
    },
    "pix": {
      "qrcode": "00020126580014br.gov.bcb.pix0136...6304ABCD",
      "end2end": "E00000000202607281200abc123def456"
    },
    "customer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "document": { "type": "cpf", "number": "12345678900" }
    },
    "createdAt": "2026-07-28T12:00:00.000Z"
  }
}

Quando a transação for de boleto, o objeto data.boleto (url, barcode, digitableLine) é enviado no lugar de data.pix.

🔹 Eventos Disponíveis

O campo data.status reflete o mesmo status retornado pelos endpoints de criação e consulta de transação:

Evento (`data.status`)	Quando é enviado
`pending`	Cobrança criada, aguardando pagamento
`processing`	Pagamento em processamento
`paid`	Pagamento confirmado (PIX/boleto)
`approved`	Pagamento aprovado (cartão)
`refused`	Pagamento recusado
`refunded`	Pagamento estornado
`chargedback`	Chargeback recebido
`in_protest`	Chargeback em contestação

🔄 Implementação Recomendada

app.post('/webhooks/velfy', async (req, res) => {
  const { data } = req.body

  // Responda rapidamente e processe de forma assíncrona
  res.status(200).send('OK')

  switch (data.status) {
    case 'paid':
    case 'approved':
      await releaseProduct(data.externalRef)
      break
    case 'refunded':
      await cancelDelivery(data.externalRef)
      break
    default:
      await logTransactionUpdate(data)
  }
})

🛡️ Boas Práticas

🔄 Idempotência

Use o campo data.id (id da transação) para não processar o mesmo evento duas vezes
Armazene o último status processado antes de agir sobre um novo evento

⚡ Performance

Responda com HTTP 200 o mais rápido possível
Processe a lógica de negócio de forma assíncrona (fila, job, etc)

📊 Monitoramento

Monitore falhas de entrega no seu endpoint
Use GET /api/v1/transactions/{id} para conciliar dados quando necessário

🎯 Próximos Passos

💰 PIX

Gere cobranças PIX com QR Code

💳 Cartão de Crédito

Tokenize e cobre no cartão

​Webhooks

​🔧 Configurando a URL de Destino

​📡 Formato da Notificação

​🔹 Eventos Disponíveis

​🔄 Implementação Recomendada

​🛡️ Boas Práticas

​🎯 Próximos Passos

💰 PIX

💳 Cartão de Crédito

Webhooks

🔧 Configurando a URL de Destino

📡 Formato da Notificação

🔹 Eventos Disponíveis

🔄 Implementação Recomendada

🛡️ Boas Práticas

🎯 Próximos Passos