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 a Pix Lerian payment flow, the X-Idempotency header is your idempotency key. Send a new value for each request, and reuse it only to retry that request. The BACEN endToEndId is not the retry key. Treat the X-Idempotency value as your idempotency key:
  • If you retry a request after a timeout, reuse the same X-Idempotency value.
  • If the first attempt succeeded, Pix Lerian replays its response for one hour.
  • If the first attempt failed with a 5xx, or the hour has passed, read the operation’s state before you retry.
  • Within that hour, if you reuse the value with a different request, Pix Lerian refuses it.
This prevents:
  • Duplicate ledger postings
  • Double debits
  • Manual operational fixes
  • Reconciliation inconsistencies
You can supply your own endToEndId. Characters 2 to 9, after the leading E, must carry your ISPB. For a key or QR Code payment, send it when you initiate the transfer, or omit it and Pix Lerian generates one. The initiation returns the value, and processing reuses it. Do not send X-End-To-End-Id when you process a key or QR Code payment: Pix Lerian refuses it. For a manual payment, send the value in X-End-To-End-Id when you process the transfer. 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. Confirm the final status through a webhook or Get Transfer:
  • Persist webhook status in your system
  • Handle both success and failure notifications
Waiting for the webhook aligns your UI to SPI-confirmed settlement. This reduces 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, but 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
Keep CRM, DICT, and Pix Lerian consistent with each other.

​
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.