Introduction
What is PIX Bacen?
The PIX Bacen API is a version of the FyPay API that follows the official specification from the Central Bank of Brazil (BACEN) for the PIX instant payment system. This version was developed to serve integrators who need compatibility with the standard BACEN format.
This API is an alternative to the standard FyPay API for the operations listed below (charge, transfer by key, refund, and balance). Both use the same base URL (https://api.fypay.me/api), the same authentication, and the same business rules; only the request and response formats change.
When should you use the PIX Bacen API?
Use this API when:
- Your system is already integrated with other PSPs that follow the BACEN specification
- You need to maintain compatibility with multiple PIX providers
- Your application was built following the official Central Bank documentation
- You prefer working with the V2 webhook format (envelope
{type, data})
Key differences
Value Format
Monetary values are strings with 2 decimal places (e.g., "123.45") instead of numbers.
Webhook Structure
With the V2 payload version (chosen per webhook), notifications use the envelope format {type, data} with status LIQUIDATED instead of CONFIRMED.
Identifiers
Uses txid for charges and e2eid for refunds, following BACEN naming conventions.
Separated Fields
Counterparty split into debtorAccount (payer) and creditorAccount (receiver).
Available endpoints
All endpoints are under the base URL https://api.fypay.me/api, with no additional prefix:
| Endpoint | Method | Description |
|---|---|---|
/api/cob/:txid | PUT | Create an immediate charge (PIX QR Code) |
/api/pix/:e2eid/devolucao/:id | PUT | Request a refund for a received PIX |
/api/dict/pix | POST | Initiate a PIX transfer (Cash-Out) |
/api/accounts/balances | GET | Query account balance |
Comparison with the standard API
| Operation | Standard API | PIX Bacen API |
|---|---|---|
| Cash-In | POST /api/pix/cash-in | PUT /api/cob/:txid |
| Cash-Out | POST /api/pix/cash-out | POST /api/dict/pix |
| Refund | POST /api/pix/refund-in/:id | PUT /api/pix/:e2eid/devolucao/:id |
| Balance | GET /api/balance | GET /api/accounts/balances |
Integration flow
sequenceDiagram
participant Client
participant FyPay
participant BACEN
Note over Client,BACEN: 1. Authentication
Client->>FyPay: POST /api/auth/token
FyPay-->>Client: access_token
Note over Client,BACEN: 2. Create Charge
Client->>FyPay: PUT /api/cob/\{txid\}
FyPay->>BACEN: Register charge
FyPay-->>Client: QR Code + data
Note over Client,BACEN: 3. Payment (via banking app)
BACEN->>FyPay: Payment webhook
FyPay->>Client: Webhook V2 (type: RECEIVE)