Skip to main content
Para mais detalhes sobre o evento TRANSFER e a descrição completa de todos os campos do payload, consulte a referência do evento TRANSFER.

​
Visão Geral

Quando uma transferência PIX é liquidada ou falha, a Plowf envia um evento TRANSFER para seu endpoint de webhook. Use esse evento para confirmar a liquidação sem precisar consultar a API repetidamente.

​
Pré-requisitos

​
1. Receber e processar o evento TRANSFER

Quando a transferência for liquidada (ou falhar), a Plowf envia um POST para seu endpoint: 
{
  "event": "TRANSFER",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PAID",
    "value": 250.00,
    "external_ref": "SAQUE-98765",
    "transfer": {
      "end_to_end": "E000000002024010112000000000001",
      "settled_at": "2024-01-01T12:00:00Z"
    }
  }
}
No seu endpoint, valide a assinatura e reaja ao status: 
const crypto = require('crypto');
const express = require('express');

const app = express();
app.use(express.json());

const WEBHOOK_TOKEN = process.env.WEBHOOK_TOKEN;

app.post('/webhooks/plowf', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const expected = crypto
    .createHmac('sha256', WEBHOOK_TOKEN)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const { event, data } = req.body;

  if (event === 'TRANSFER') {
    if (data.status === 'PAID') {
      // Transferência liquidada — libere o fluxo no seu sistema
      console.log('Transferência confirmada:', data.uuid, 'Ref:', data.external_ref);
      console.log('End-to-end:', data.transfer.end_to_end);
    } else if (data.status === 'FAILED') {
      // Transferência falhou — notifique e trate o reenvio
      console.error('Transferência falhou:', data.uuid);
    }
  }

  res.status(200).json({ received: true });
});
Consulte a página de validação de assinatura para exemplos em Python e PHP.

​
2. Tratar falhas

Se a transferência falhar (FAILED), o valor não é debitado. Você pode criar uma nova transferência para reenviar: 
async function reenviarTransferencia(transferenciaOriginal) {
  const response = await fetch('https://app.plowf.com/api/v1/transfers', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PLOWF_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      value: transferenciaOriginal.value,
      pix_key: transferenciaOriginal.pix_key,
      external_ref: `${transferenciaOriginal.external_ref}-RETRY`,
    }),
  });

  return response.json();
}

​
Status possíveis no evento TRANSFER

StatusSignificado
PENDINGAguardando processamento
PROCESSINGEm processamento no sistema PIX
PAIDLiquidada com sucesso
FAILEDFalhou — valor não debitado
CANCELLEDCancelada antes do processamento
REFUNDEDValor estornado
PARTIALLY_REFUNDEDValor estornado parcialmente

​
Boas práticas

  • Idempotência: Use o uuid da transferência para evitar processar o mesmo evento mais de uma vez.
  • Nunca confirme por polling: Aguarde o webhook PAID antes de considerar a transferência concluída.
  • Trate FAILED imediatamente: Notifique o usuário e registre a causa para diagnóstico.

​
Referências