Descripción General

{
  "data": {
    "...": "datos del evento"
  },
  "type": "RECEIVE"
}

interface WebhookV2Data {
  id: number | null;
  txId: string | null;
  endToEndId: string | null;
  providerId: string | null;

  pixKey: string | null;

  status: 'PENDING' | 'LIQUIDATED' | 'REFUNDED' | 'ERROR';

  payment: {
    amount: string;
    currency: 'BRL';
  };
  mismatchAmount?: string | null;

  refunds: RefundInfo[];

  createdAt: string;
  errorCode: string | null;

  webhookType: 'RECEIVE' | 'TRANSFER' | 'REFUND';
  creditDebitType: 'CREDIT' | 'DEBIT';
  transactionType: 'PIX';
  localInstrument: 'DICT';

  debtorAccount: AccountInfo;
  creditorAccount: AccountInfo;

  idempotencyKey: string | null;

  ticketData: Record<string, unknown>;
  remittanceInformation: string | null;
}

interface AccountInfo {
  ispb: string | null;
  name: string | null;
  bankName: string | null;
  issuer: string | null;
  number: string | null;
  document: string | null;
  accountType: string | null;
}

interface RefundInfo {
  status: 'PENDING' | 'LIQUIDATED' | 'ERROR';
  payment: {
    amount: number;
    currency: 'BRL';
  };
  errorCode: string | null;
  eventDate: string;
  endToEndId: string | null;
  information: string | null;
}

debtorAccount = Quien pagó (contraparte)
creditorAccount = Su cuenta (campos null)
creditDebitType = CREDIT

debtorAccount = Su cuenta (campos null)
creditorAccount = Quien recibió (contraparte)
creditDebitType = DEBIT

debtorAccount = Su cuenta (campos null)
creditorAccount = Quien recibe de vuelta (contraparte)
creditDebitType = DEBIT

debtorAccount = Quien está devolviendo (contraparte)
creditorAccount = Su cuenta (campos null)
creditDebitType = CREDIT

import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const WEBHOOK_SECRET = process.env.FYPAY_WEBHOOK_SECRET!;
const processed = new Set<string>();

function isValidSignature(rawBody: Buffer, signature: string | undefined) {
  if (!signature) return false;
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

function dedupKey(webhook: WebhookV2) {
  const { type, data } = webhook;
  if (type === 'REFUND') {
    const refund = data.refunds[0];
    return `REFUND:${refund?.endToEndId ?? data.providerId}:${refund?.status}`;
  }
  return `${type}:${data.id ?? data.idempotencyKey}:${data.status}`;
}

app.post('/webhooks/pix', (req, res) => {
  if (!isValidSignature(req.body, req.header('x-avista-signature'))) {
    return res.status(401).end();
  }

  const webhook: WebhookV2 = JSON.parse(req.body.toString('utf8'));
  res.status(200).json({ acknowledged: true });

  const key = dedupKey(webhook);
  if (processed.has(key)) return;
  processed.add(key);

  switch (webhook.type) {
    case 'RECEIVE':
      handleReceive(webhook.data);
      break;
    case 'TRANSFER':
      handleTransfer(webhook.data);
      break;
    case 'REFUND':
      handleRefund(webhook.data);
      break;
  }
});

function handleReceive(data: WebhookV2Data) {
  if (data.status === 'LIQUIDATED') {
    console.log(`PIX recibido: R$ ${data.payment.amount}`);
  }
}

function handleTransfer(data: WebhookV2Data) {
  if (data.status === 'LIQUIDATED') {
    console.log(`PIX enviado: ${data.endToEndId}`);
  } else if (data.status === 'ERROR') {
    console.log(`PIX falló: ${data.errorCode}`);
  }
}

function handleRefund(data: WebhookV2Data) {
  const refund = data.refunds[0];
  if (data.status === 'REFUNDED') {
    console.log(`Devolución: R$ ${refund.payment.amount}`);
  }
}