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 an idempotent payment key

On the Pix payment flow, the BACEN endToEndId is your idempotency key. It is a unique, immutable 32-character identifier that you supply, or that Pix Lerian generates. You can retry safely only when you own the value. Treat the endToEndId as your idempotency key:
  • If you retry a request after a timeout, reuse the same endToEndId.
  • If the first attempt already created the payment, Pix Lerian replays the existing one.
  • If the first attempt failed before processing, the retry creates the payment exactly once.
This prevents:
  • Duplicate ledger postings
  • Double debits
  • Manual operational fixes
  • Reconciliation inconsistencies
Never generate a new endToEndId for a retry. For the header-level idempotency behavior of each Lerian product, see Retries and idempotency.

​
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:
  • Display 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.

​
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

​
5. Monitor pending transactions & background jobs

A Pix can enter PENDING while waiting for:
  • Provider processing
  • SPI acknowledgment
  • Webhook delivery
  • Retry cycles
Pix Lerian 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 Lerian 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 regulatory behavior.

​
8. Implement reconciliation and accounting validation

Reconciliation closes the loop between:
  • Your system
  • Pix Lerian
  • 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.