功能激活

概述

PIX Bacen 模式包含两个相互独立的部分：

BACEN 端点：兼容中央银行规范的端点。任何已认证的账户都可以使用，无需激活：只需使用与标准 API 相同的 Bearer 令牌。
V2 Webhooks：使用 {type, data} 信封的通知格式。由客户自行 按 webhook（按已注册的 URL）选择。

将 webhook 切换为 V2 对该 URL 的使用方而言是一项 破坏性变更：payload 格式将完全不同。请在切换版本前更新处理器。

如何启用 V2 Webhooks

1. 通过控制面板

在 FyPay 控制面板中进入 设置 → Webhooks，注册（或重新注册）目标事件的 URL，并在 负载版本 中选择 PIX BACEN（V2）。版本只能在控制面板中配置。

2. 测试集成

切换版本后：

通过 PUT /api/cob/:txid 创建一笔测试收款
确认 V2 webhook 已正确送达
确认您的应用已处理新格式

有哪些变化？

Endpoints

BACEN 端点与标准 API 的以下操作相对应：

标准 API	PIX Bacen API
`POST /api/pix/cash-in`	`PUT /api/cob/:txid`
`POST /api/pix/cash-out`	`POST /api/dict/pix`
`POST /api/pix/refund-in/:id`	`PUT /api/pix/:e2eid/devolucao/:id`
`GET /api/balance`	`GET /api/accounts/balances`

标准 API 的端点仍可正常使用。您可以同时使用两套 API。

Webhooks

Webhook 格式完全改变：

{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionId": "12345",
  "movementType": "CREDIT",
  "originalAmount": 100.00,
  "finalAmount": 100.00,
  "counterpart": {
    "name": "João Silva",
    "document": "123.xxx.xxx-xx"
  }
}

{
  "type": "RECEIVE",
  "data": {
    "id": 123,
    "txId": "abc123",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "100.00",
      "currency": "BRL"
    },
    "creditDebitType": "CREDIT",
    "debtorAccount": {
      "name": "João Silva",
      "document": "123.xxx.xxx-xx"
    },
    "creditorAccount": {...}
  }
}

Webhook 的主要区别

方面	V1	V2
结构	字段位于根级	`{type, data}` 信封
事件类型	`event: "CashIn"`	`type: "RECEIVE"`
成功状态	`CONFIRMED`	`LIQUIDATED`
退款状态	`CONFIRMED`	`REFUNDED`
金额	`number` (100.00)	`string` ("100.00")
交易对手	`counterpart`	`debtorAccount` / `creditorAccount`

准备您的集成

1. 更新 webhook 处理器

// 之前 (V1)
function handleWebhookV1(payload: any) {
  if (payload.event === 'CashIn' && payload.status === 'CONFIRMED') {
    processPayment(payload.transactionId, payload.finalAmount);
  }
}

// 之后 (V2)
function handleWebhookV2(payload: any) {
  if (payload.type === 'RECEIVE' && payload.data.status === 'LIQUIDATED') {
    const amount = parseFloat(payload.data.payment.amount);
    processPayment(payload.data.id, amount);
  }
}

2. 更新类型/接口

// V2 Types
interface WebhookV2Payload {
  type: 'RECEIVE' | 'TRANSFER' | 'REFUND';
  data: WebhookV2Data;
}

interface WebhookV2Data {
  id: number | null;
  txId: string | null;
  status: 'PENDING' | 'LIQUIDATED' | 'REFUNDED' | 'ERROR';
  payment: {
    amount: string;  // 注意：是 string，不是 number！
    currency: string;
  };
  creditDebitType: 'CREDIT' | 'DEBIT';
  debtorAccount: AccountInfo;
  creditorAccount: AccountInfo;
  endToEndId: string | null;
  refunds: RefundInfo[];
  // ... 其他字段
}

3. 使用额外的 URL 测试

在切换正在使用的 URL 的版本之前：

在同一事件中额外注册一个使用 PIX BACEN 版本的测试 URL（每个事件最多接受 3 个 URL，且每个 URL 有各自的版本）
完整测试 Cash-In、Cash-Out 和 Refund
确认所有 webhook 均被正确处理

Rollback

版本可以随时切换回 V1：在控制面板（设置 → Webhooks）中为该 URL 选择标准版本（V1）。

建议在过渡期间同时支持两个版本：

function handleWebhook(payload: any) {
  // 根据格式检测版本
  if (payload.type && payload.data) {
    return handleWebhookV2(payload);
  } else if (payload.event) {
    return handleWebhookV1(payload);
  }
  throw new Error('未知的 webhook 格式');
}