简介

什么是 PIX Bacen？

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

对于下列操作（收款、按密钥转账、退款和余额查询），此 API 是标准 FyPay API的替代方案。两者使用相同的基础 URL（https://api.fypay.me/api）、相同的认证方式和相同的业务规则，仅请求和响应格式不同。

何时应使用 PIX Bacen API？

在以下情况下使用此 API：

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

主要区别

金额格式

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

Webhook 结构

使用 V2 负载版本（按 webhook 选择）时，通知使用信封格式 {type, data}，状态为 LIQUIDATED 而非 CONFIRMED。

标识符

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

分离字段

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

可用接口端点

所有端点都位于基础 URL https://api.fypay.me/api 下，没有额外前缀：

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

与标准 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`

集成流程

sequenceDiagram
    participant Client
    participant FyPay
    participant BACEN

    Note over Client,BACEN: 1. 身份认证
    Client->>FyPay: POST /api/auth/token
    FyPay-->>Client: access_token

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

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