Visão Geral

{
  "type": "RECEIVE" | "TRANSFER" | "REFUND",
  "data": {
    // Dados específicos do evento
  }
}

interface WebhookV2Data {
  // Identificadores
  id: number;                    // ID da transação
  txId: string | null;           // Identificador da cobrança (txid)
  endToEndId: string | null;     // End to End ID da transação PIX

  // Chave PIX
  pixKey: string | null;         // Chave PIX utilizada

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

  // Pagamento
  payment: {
    amount: string;              // Valor (string com 2 decimais)
    currency: string;            // Moeda (BRL)
  };

  // Devoluções
  refunds: RefundInfo[];         // Lista de devoluções (vazio se não houver)

  // Datas
  createdAt: string;             // Data de criação (ISO 8601)

  // Erro
  errorCode: string | null;      // Código de erro (se houver)

  // Tipo de operação
  webhookType: 'RECEIVE' | 'TRANSFER' | 'REFUND';
  creditDebitType: 'CREDIT' | 'DEBIT';
  transactionType: 'PIX';
  localInstrument: 'DICT';

  // Contas
  debtorAccount: AccountInfo;    // Pagador/Remetente
  creditorAccount: AccountInfo;  // Recebedor/Destinatário

  // Idempotência
  idempotencyKey: string | null;

  // Dados adicionais
  ticketData: object;
  remittanceInformation: string | null;  // Descrição da transação
}

interface AccountInfo {
  ispb: string | null;           // Código ISPB do banco
  name: string | null;           // Nome do banco
  issuer: string | null;         // Código do banco
  number: string | null;         // Número da conta
  document: string | null;       // CPF/CNPJ (mascarado)
  accountType: string | null;    // Tipo de conta
}

interface RefundInfo {
  status: 'PENDING' | 'LIQUIDATED' | 'ERROR';
  payment: {
    amount: number;              // Valor do refund (number!)
    currency: string;
  };
  errorCode: string | null;
  eventDate: string;             // Data do refund
  endToEndId: string | null;     // E2E ID do refund
  information: string | null;    // Descrição do refund
}

debtorAccount = Quem pagou (contraparte)
creditorAccount = Sua conta (recebedor)
creditDebitType = CREDIT

debtorAccount = Sua conta (pagador)
creditorAccount = Quem recebeu (contraparte)
creditDebitType = DEBIT

debtorAccount = Sua conta (devolvendo)
creditorAccount = Quem vai receber de volta (contraparte)
creditDebitType = DEBIT

debtorAccount = Quem está devolvendo (contraparte)
creditorAccount = Sua conta (recebendo de volta)
creditDebitType = CREDIT

Authorization: Basic base64(username:password)

import express from 'express';

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

interface WebhookV2 {
  type: 'RECEIVE' | 'TRANSFER' | 'REFUND';
  data: WebhookV2Data;
}

// Set para idempotência
const processedIds = new Set<number>();

app.post('/webhooks/pix', (req, res) => {
  const webhook: WebhookV2 = req.body;

  // Responder rapidamente
  res.status(200).json({ acknowledged: true });

  // Verificar idempotência
  if (processedIds.has(webhook.data.id)) {
    console.log(`Webhook ${webhook.data.id} já processado`);
    return;
  }
  processedIds.add(webhook.data.id);

  // Processar por tipo
  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') {
    const amount = parseFloat(data.payment.amount);
    console.log(`PIX recebido: R$ ${amount}`);
    // Creditar no sistema
  }
}

function handleTransfer(data: WebhookV2Data) {
  if (data.status === 'LIQUIDATED') {
    console.log(`PIX enviado: ${data.endToEndId}`);
    // Confirmar transferência
  } else if (data.status === 'ERROR') {
    console.log(`PIX falhou: ${data.errorCode}`);
    // Reverter operação
  }
}

function handleRefund(data: WebhookV2Data) {
  if (data.status === 'REFUNDED') {
    const refund = data.refunds[0];
    console.log(`Devolução: R$ ${refund.payment.amount}`);
    // Processar devolução
  }
}