激活前	激活后
`POST /pix/cash-in`	`PUT /cob/:txid`
`POST /pix/cash-out`	`POST /dict/pix`
`POST /pix/:id/refund`	`PUT /pix/:e2eid/devolucao/:id`
`GET /balance`	`GET /accounts/balances`

旧接口端点仍然可用。您可以同时使用两套 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 类型定义
interface WebhookV2Payload {
  type: 'RECEIVE' | 'TRANSFER' | 'REFUND';
  data: WebhookV2Data;
}

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

3. 在开发环境中测试

在申请生产环境激活之前：

在沙盒环境中申请激活
对收款、转账和退款进行完整测试
验证所有 Webhook 均被正确处理

回滚

激活后无法自动恢复到 V1。如需回滚，请联系技术支持。

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

function handleWebhook(payload: any) {
  // 通过格式检测版本
  if (payload.type && payload.data) {
    return handleWebhookV2(payload);
  } else if (payload.event) {
    return handleWebhookV1(payload);
  }
  throw new Error('Unknown webhook format');
}