概述

{
  "type": "RECEIVE" | "TRANSFER" | "REFUND",
  "data": {
    // 事件特定数据
  }
}

interface WebhookV2Data {
  // 标识符
  id: number;                    // 交易 ID
  txId: string | null;           // 收款标识符（txid）
  endToEndId: string | null;     // PIX 交易的端到端 ID

  // PIX 密钥
  pixKey: string | null;         // 使用的 PIX 密钥

  // 状态
  status: 'PENDING' | 'LIQUIDATED' | 'REFUNDED' | 'ERROR';

  // 付款
  payment: {
    amount: string;              // 金额（带 2 位小数的字符串）
    currency: string;            // 货币（BRL）
  };

  // 退款
  refunds: RefundInfo[];         // 退款列表（如无则为空）

  // 日期
  createdAt: string;             // 创建日期（ISO 8601）

  // 错误
  errorCode: string | null;      // 错误码（如有）

  // 操作类型
  webhookType: 'RECEIVE' | 'TRANSFER' | 'REFUND';
  creditDebitType: 'CREDIT' | 'DEBIT';
  transactionType: 'PIX';
  localInstrument: 'DICT';

  // 账户
  debtorAccount: AccountInfo;    // 付款方/发送方
  creditorAccount: AccountInfo;  // 收款方/接收方

  // 幂等性
  idempotencyKey: string | null;

  // 附加数据
  ticketData: object;
  remittanceInformation: string | null;  // 交易描述
}

interface AccountInfo {
  ispb: string | null;           // 银行 ISPB 代码
  name: string | null;           // 银行名称
  issuer: string | null;         // 银行代码
  number: string | null;         // 账号
  document: string | null;       // CPF/CNPJ（已脱敏）
  accountType: string | null;    // 账户类型
}

interface RefundInfo {
  status: 'PENDING' | 'LIQUIDATED' | 'ERROR';
  payment: {
    amount: number;              // 退款金额（数值类型！）
    currency: string;
  };
  errorCode: string | null;
  eventDate: string;             // 退款日期
  endToEndId: string | null;     // 退款 E2E ID
  information: string | null;    // 退款描述
}

debtorAccount = 付款方（交易对手）
creditorAccount = 您的账户（收款方）
creditDebitType = CREDIT

debtorAccount = 您的账户（付款方）
creditorAccount = 收款方（交易对手）
creditDebitType = DEBIT

debtorAccount = 您的账户（退款方）
creditorAccount = 退款接收方（交易对手）
creditDebitType = DEBIT

debtorAccount = 退款方（交易对手）
creditorAccount = 您的账户（退款接收方）
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;
}

// 用于幂等性的集合
const processedIds = new Set<number>();

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

  // 立即响应
  res.status(200).json({ acknowledged: true });

  // 检查幂等性
  if (processedIds.has(webhook.data.id)) {
    console.log(`Webhook ${webhook.data.id} already processed`);
    return;
  }
  processedIds.add(webhook.data.id);

  // 按类型处理
  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 received: R$ ${amount}`);
    // 在系统中入账
  }
}

function handleTransfer(data: WebhookV2Data) {
  if (data.status === 'LIQUIDATED') {
    console.log(`PIX sent: ${data.endToEndId}`);
    // 确认转账
  } else if (data.status === 'ERROR') {
    console.log(`PIX failed: ${data.errorCode}`);
    // 回滚操作
  }
}

function handleRefund(data: WebhookV2Data) {
  if (data.status === 'REFUNDED') {
    const refund = data.refunds[0];
    console.log(`Refund: R$ ${refund.payment.amount}`);
    // 处理退款
  }
}