Skip to main content
Following the practices below helps ensure predictable behavior, operational safety, and compliance with BACEN’s expectations — especially under volume, network instability, or dispute scenarios. These recommendations apply to all Pix use cases: wallets, merchant payments, cash-outs, QR Code flows, recurring operations, and internal transfers.

​
1. Use idempotent transaction IDs

Always send a unique and immutable transactionId created by your system. Treat it as your idempotency key:
  • If you retry a request due to timeout, reuse the same ID.
  • If the first attempt succeeded, the Pix Plugin will return the same result.
  • If the first attempt failed before processing, the retry will create the transaction exactly once.
This prevents:
  • Duplicate ledger postings
  • Double debits
  • Manual operational fixes
  • Reconciliation inconsistencies
Never generate a new ID during a retry.

​
2. Rely on webhooks for final transaction status

A 200 OK from the API does not guarantee the Pix was completed. It only means the request entered the orchestration flow. The authoritative status is the webhook:
  • Displays final status to the user only after webhook confirmation
  • Persist webhook status in your system
  • Handle both success and failure notifications
Waiting for the webhook aligns your UI to SPI-confirmed settlement, reducing disputes and false positives.

​
3. Validate webhook authenticity

Every webhook includes an HMAC signature (e.g., X-Signature). Best practices:
  • Store the secret in a vault
  • Recompute the HMAC using the raw request body
  • Compare with the header
  • Reject and log mismatches
This protects against:
  • Fake callbacks
  • Tampered payloads
  • Unauthorized requests hitting your endpoint
Webhook security is a PSP-level requirement — treat it as such.

​
4. Design for failure and retries

Pix is instant; the network around it is not. Expect failures in:
  • PSTI / direct provider connectivity
  • Telecom / SMS delivery (for key confirmation)
  • Network timeouts
  • Internal ledger validations
  • Limit and anti-fraud checks (regulated)
Recommended approach:
  • Implement clear retry policies (exponential backoff, controlled loops)
  • Never retry blindly
  • Surface actionable messages to the user
  • Log all failures with correlation IDs
  • Treat “pending” as a normal intermediary state
A robust Pix integration is resilient by design.

​
5. Monitor pending transactions & background jobs

A Pix can enter PENDING while waiting for:
  • Provider processing
  • SPI acknowledgment
  • Webhook delivery
  • Retry cycles
The Pix Plugin runs background workers to guarantee eventual consistency:
  • Retry callbacks
  • Reconcile intermediate states
  • Detect stuck operations
Your responsibilities:
  • Monitor pending transactions regularly
  • Configure alerts for excessive retry attempts
  • Integrate logs, metrics, and traces for observability
Pending ≠ failure, but prolonged pending requires investigation.

​
6. Keep Pix keys and customer data synchronized

Because keys are tied to identity:
  • If a user changes phone/email → update or remove associated Pix keys
  • Keep CRM records aligned with DICT data
  • Remove outdated keys to avoid misrouting
  • For institutions using DICT: Ensure portability and ownership claims follow BACEN rules
This reduces:
  • Payments to wrong recipients
  • MED cases due to incorrect keys
  • Support friction
Consistency between CRM ↔ DICT ↔ Pix Plugin is essential.

​
7. Respect SLA expectations and time windows

Pix settlement occurs in up to 10 seconds, but legal SLAs matter too. Design your UX to respect:
  • Maximum SPI tolerances
  • Nighttime limit adjustments (20:00–06:00)
  • Customer-driven limit reduction delays (immediate)
  • Customer-driven limit increases (may require authentication or waiting period)
Always display:
  • “Processing…” while awaiting confirmation
  • “Try again” guidance for limit breaches
Your UX must mirror Pix’s real regulatory behavior.

​
8. Implement reconciliation and accounting validation

Reconciliation closes the loop between:
  • Your system
  • The Pix Plugin
  • SPI settlement
  • Ledger postings (Midaz)
Recommended reconciliation cycle:
  • Confirm every settled Pix using your webhook log
  • Match every Pix ID with a ledger posting
  • Compare daily summaries with provider/SPB outputs
  • Flag any mismatch for manual review
This reduces operational noise and supports audit readiness.

​
9. Test end-to-end with realistic flows

Before going live, simulate:
  • Cash-in and cash-out
  • High-value limits
  • Invalid keys
  • Expired QR Codes
  • Refunds (inbound + outbound)
  • MED-related refund triggers
  • Webhook downtime
  • API timeout and retry patterns
Also test intra-ledger Pix scenarios when both accounts exist in Midaz. Your validation checklist:
  • Correct ledger postings
  • Correct Pix status transitions
  • Proper webhook handling
  • Proper limit enforcement
  • Proper accounting behavior

​
10. Prepare your support and operations teams

Support teams should understand:
  • Pix timeframes (including night limit rules)
  • Difference between “initiated”, “pending”, “completed”, “refunded”, “failed”
  • How to read E2E IDs
  • How to track DICT issues
  • When MED applies vs normal refunds
Clear support flows reduce user friction and avoid false MED disputes.