> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Pix is a real-time payment system, but a reliable integration depends on more than just calling APIs.

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, Pix Switch 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.**

In addition, Pix Switch supports the IETF-standard `Idempotency-Key` HTTP header on payment creation and return initiation endpoints. The middleware replays the full cached response transparently for duplicate requests (Pix Switch does not return the `X-Idempotency-Replayed` header). For full details, see [Retries and idempotency](/en/reference/retries-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 — 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 reliable 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

Pix Switch 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 Switch 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
* Pix Switch
* 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.