简介

什么是 PIX Bacen？

PIX Bacen API 是 Avista API 的一个版本，遵循巴西中央银行（BACEN）关于 PIX 即时支付系统的官方规范。该版本专为需要兼容 BACEN 标准格式的集成商而开发。

此 API 是标准 Avista API的替代方案。两者提供相同的功能，但请求和响应格式不同。

何时应使用 PIX Bacen API？

在以下情况下使用此 API：

您的系统已与其他遵循 BACEN 规范的 PSP 集成
您需要保持与多个 PIX 提供商的兼容性
您的应用程序是按照中央银行官方文档构建的
您更倾向于使用 V2 Webhook 格式（信封结构 {type, data}）

主要区别

金额格式

货币金额为带 2 位小数的字符串（例如 "123.45"），而非数值类型。

Webhook 结构

Webhook 使用信封格式 {type, data}，状态为 LIQUIDATED 而非 CONFIRMED。

标识符

使用 txid 标识收款请求，使用 e2eid 标识退款，遵循 BACEN 命名约定。

分离字段

交易对手拆分为 debtorAccount（付款方）和 creditorAccount（收款方）。

可用接口端点

端点	方法	描述
`/cob/:txid`	PUT	创建即时收款（PIX 二维码）
`/pix/:e2eid/devolucao/:id`	PUT	请求退还已收到的 PIX
`/dict/pix`	POST	发起 PIX 转账（Cash-Out）
`/accounts/balances`	GET	查询账户余额

与标准 API 的对比

操作	标准 API	PIX Bacen API
收款	`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`

集成流程

sequenceDiagram
    participant Client
    participant Avista
    participant BACEN

    Note over Client,BACEN: 1. 身份认证
    Client->>Avista: POST /oauth/token
    Avista-->>Client: access_token

    Note over Client,BACEN: 2. 创建收款
    Client->>Avista: PUT /cob/\{txid\}
    Avista->>BACEN: Register charge
    Avista-->>Client: QR Code + data

    Note over Client,BACEN: 3. 付款（通过银行应用）
    BACEN->>Avista: Payment webhook
    Avista->>Client: Webhook V2 (type: RECEIVE)