Webhooks de Cobrança

Eventos relacionados ao ciclo de vida das cobranças (charges) na FastPay.

Eventos Disponíveis

Evento	Descrição
charge.created	Enviado quando uma nova cobrança é criada
charge.pending	Enviado quando uma cobrança está aguardando pagamento
charge.paid	Enviado quando uma cobrança é paga com sucesso
charge.updated	Enviado quando qualquer campo da cobrança é atualizado

Payload

charge.created

Enviado imediatamente após a criação de uma nova cobrança.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.created",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "pending",
    "amount": 100.00,
    "currency": "BRL",
    "paymentMethod": {
      "type": "pix"
    },
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": {
        "type": "cpf",
        "id": "12345678900"
      }
    },
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

charge.pending

Enviado quando a cobrança está aguardando pagamento (ex: PIX gerado, boleto emitido).

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.pending",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "pending",
    "amount": 100.00,
    "currency": "BRL",
    "paymentMethod": {
      "type": "pix",
      "qrCode": "00020126...",
      "qrCodeBase64": "data:image/png;base64,...",
      "expiresAt": "2024-01-16T10:30:00.000Z"
    },
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com"
    },
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

charge.paid

Enviado quando o pagamento é confirmado com sucesso.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.paid",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "paid",
    "amount": 100.00,
    "currency": "BRL",
    "paymentMethod": {
      "type": "pix"
    },
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com"
    },
    "paidAt": "2024-01-15T10:35:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

charge.updated

Enviado quando qualquer campo da cobrança é atualizado.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.updated",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "paid",
    "amount": 100.00,
    "currency": "BRL",
    "paymentMethod": {
      "type": "pix"
    },
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com"
    },
    "updatedAt": "2024-01-15T10:40:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Exemplo de Implementação

app.post('/webhooks/fastpay', (req, res) => {
  const { id, event, data } = req.body;

  switch (event) {
    case 'charge.created':
      console.log(`Nova cobrança criada: ${data.id}`);
      break;

    case 'charge.pending':
      console.log(`Cobrança aguardando pagamento: ${data.id}`);
      // Enviar QR Code ou link de pagamento para o cliente
      break;

    case 'charge.paid':
      console.log(`Pagamento confirmado: ${data.id}`);
      // Liberar acesso ao produto/serviço
      // Atualizar status do pedido
      // Enviar email de confirmação
      break;

    case 'charge.updated':
      console.log(`Cobrança atualizada: ${data.id}`);
      break;

    default:
      console.log(`Evento desconhecido: ${event}`);
  }

  res.status(200).send('OK');
});

Fluxo Típico