> ## 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

> Best practices for reliable Pix integrations: idempotent endToEndId keys, webhook confirmation, HMAC signatures, and retry and observability patterns.

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](/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.

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