Integrating PIX with Bradesco's API

PIX, Brazil's instant payment system launched by the Banco Central do Brasil, has fundamentally transformed how money moves in Brazil. Available 24/7/365, PIX transfers settle in seconds. Bradesco provides a developer API that lets you generate PIX charges, process payments, and receive real-time notifications — all programmatically.

Understanding PIX API Use Cases

Before writing a single line of code, clarify which PIX flow your application needs:

  • Static QR Code (QR Estático) — A fixed QR code for a merchant; amount is entered by the payer. Great for simple donation buttons or point-of-sale displays.
  • Dynamic QR Code (QR Dinâmico) — A unique QR code per transaction, containing the exact amount and reference. Ideal for e-commerce checkouts.
  • PIX Cobrança (Billing PIX) — Dynamic QR with expiry, discount, fine, and interest support. Designed for recurring billing or invoices.
  • Payment Initiation via Open Banking — Initiating a PIX transfer from a user's Bradesco account through Open Finance consent flows.

Setting Up PIX: Prerequisites

To use Bradesco's PIX API, you'll need:

  1. An active Bradesco business account with a registered PIX key (CNPJ, email, phone, or random key)
  2. API credentials (Client ID and Client Secret) from the Bradesco developer portal
  3. A valid SSL certificate for mTLS — required for PIX endpoints in production
  4. A webhook endpoint on your server to receive PIX payment notifications

Generating a Dynamic PIX Charge

The core flow for a Dynamic PIX QR Code involves:

  1. Authenticate — Obtain a Bearer token using OAuth 2.0 with the cob.write scope.
  2. Create a Cobrança (cob) — POST to /v2/cob with the transaction value, expiry (in seconds), and debtor information (optional).
  3. Receive the txid — Bradesco returns a unique transaction ID (txid) and the encoded payload (pixCopiaECola).
  4. Generate the QR Code — Use the pixCopiaECola string to render a QR code image on your UI using any standard QR code library.
  5. Check Payment Status — Poll GET /v2/cob/{txid} or, better yet, receive a webhook notification when the payment is confirmed.

Handling PIX Webhooks

Webhooks are the recommended way to handle payment confirmations. When a PIX payment is received, Bradesco will POST a notification to your registered webhook URL containing the txid, paid amount, payer details, and timestamp.

Best practices for PIX webhook handling:

  • Always validate the incoming payload against the expected txid before marking an order as paid.
  • Respond with HTTP 200 OK immediately — do heavy processing asynchronously.
  • Implement idempotency: duplicate webhook deliveries can occur, so check if you've already processed a given txid.
  • Verify the request signature/certificate to confirm it originates from Bradesco.

PIX Cobrança vs. Boleto: When to Use Which

Feature PIX Cobrança Boleto
Settlement Speed Instant (seconds) 1–2 business days
Availability 24/7/365 Business hours
Payment Method QR Code / Copy-Paste key Barcode / Bank slip
Expiry Control Seconds to days Days

For most modern e-commerce and fintech applications, PIX Cobrança is the preferred choice due to its speed. Boleto remains relevant for customers without smartphones or internet banking access.

Testing in Sandbox

Bradesco's sandbox environment simulates PIX flows fully. You can create mock cobranças, simulate payments (using sandbox-specific tools), and trigger webhook callbacks to test your full end-to-end flow before going live.