PIX payment gateway integration with automatic reconciliation for e‑commerce

By Kevin Marcondes · Published on Oct 28, 2026 · 6 min read

Hands holding a smartphone showing charts and numbers on the screen, blurred background — Financial data view on a smartphone, suitable for reconciliation and control Photo: IqbalStock / Pixabay

PIX payment gateway integration with automatic reconciliation for e‑commerce: implement dynamic QR codes at checkout, confirm payments in seconds and auto‑settle orders. Build reliable webhooks, daily reconciliation routines and return processes with structured logs and audits. A solid technical design prevents mismatches between gateway, store and ERP.

What a PIX integration with reconciliation delivers in practice

The goal is to connect your checkout to PIX using dynamic QR codes, real‑time status updates and automatic reconciliation between the gateway and your store. The flow covers charge creation, confirmation via webhook, order settlement, refunds and reliable reprocessing.

Reconciliation compares gateway events with orders, prevents duplicates and produces verification reports. You gain cash‑flow predictability, fewer “I paid but it didn't register” tickets and less manual spreadsheet work.

Dynamic PIX QR code at checkout that expires at the correct time.
Automatic order status updates (paid, expired, refunded).
Verifiable, failure‑tolerant webhooks (retries and deduplication).
Daily reconciliation routine and safe reprocessing.
PIX refunds (full or partial) with traceability.
Structured reports and logs for financial audit.

Signs your store needs a better PIX integration

Some symptoms show that the current integration can't handle volume. If you recognize these issues, it's worth reviewing the technical design and reconciliation.

Paid orders that don't settle due to missing confirmations.
Manual reconciliation taking too long to close the books.
Many duplicate payments or value mismatches.
QR codes expiring incorrectly or being reused improperly.
Difficulty tracking refunds and disputes.
Intermittent webhook errors without reliable reprocessing.

How the PIX flow works in the store checkout

A typical flow creates a dynamic charge, displays the QR code, waits for payment and receives gateway confirmation. For resilience, use the webhook as the primary source and controlled polling as a fallback.

Relevant states include: created, expired, paid, refund initiated and refund completed. Each transition must update the order idempotently and record audit trails.

Create the charge with amount, due date and TXID.
Display the dynamic PIX QR code and copy‑and‑paste payload.
Confirmation via webhook; fallback with limited polling.
Update the order with deduplication using TXID/E2E ID.
Automatic QR expiration and session cleanup.

Automatic reconciliation: rules, windows and exceptions

Reconciliation matches gateway events to orders by TXID/E2E ID, amount and date. Define a tolerance window for delays, batch settlement routines and a reprocessor for retained messages. Discrepancies become an exceptions queue with assisted manual handling.

ERP integrations can use queues and idempotency to keep inventory and billing synchronized across systems reliably.

Match by TXID/E2E ID + exact order amount.
Automatic reprocessing for un‑applied webhooks.
Record differences (amount mismatch, nonexistent order, duplicate).
Daily reports with reconciled totals and outstanding items.
Export to ERP and receive fiscal status updates.

Event	Source	Action in store	Notes
Charge created	Store	Await payment	Sets expiration and locks amount.
Payment received	Gateway	Settle order and continue flow	Idempotent by TXID/E2E ID.
Charge expired	Gateway/Store	Cancel reservation and clear QR	Offer a new QR for a new order.
Refund initiated	Store/Gateway	Mark refund in progress	Track reason and operator.
Refund completed	Gateway	Finalize refund and notify customer	Record transaction reference.

Security, idempotency and observability for webhooks

Webhooks must be authenticated and validated before applying changes. Sign and verify messages, rotate secrets and use queues with retry and backoff. Implement deduplication to avoid double settlement and keep immutable audit trails.

For continuous operations, monitor webhook success rates, latency and dead‑letters, with alerts and checkout health dashboards.

HMAC signature and payload verification.
Idempotency using a unique key (TXID/E2E ID).
Queues, exponential retries and a DLQ.
Structured logs and request correlation per order.
Alerts for reconciliation or refund failures.

Work stages: from diagnosis to validation

The process follows clear stages, adapted to your context and platform. The goal is to reduce risk, give the team visibility and prove the end‑to‑end flow before production.

Diagnosis: review checkout, gateway and cash processes.
Technical design: event models, states and reconciliation.
Implementation: APIs, webhooks, queues and persistence.
Validation: sandbox, end‑to‑end tests and load testing.
Assisted go‑live and tuning of monitoring and alerts.

Deliverables: documentation, tests and operations

Beyond code, value lies in the ability to operate the flow under pressure. Document the API contract, support runbooks and contingency procedures. Automated tests cover critical cases like duplicate payments and partial refunds.

Reports and dashboards simplify financial routines: daily reconciliation, outstanding items, refund timelines and operational SLAs.

Documented API contract and event schema.
Automated end‑to‑end tests for main flows.
Dashboards and alerts for webhook health.
Playbooks for failures and safe reprocessing.
Reconciliation reports and ERP export.

Frequently asked questions

Dynamic vs static PIX: which to use in e‑commerce?

For checkout, prefer dynamic PIX. It generates a unique QR per order, with expiration and a locked amount, reducing incorrect payments and reuse. Static PIX is suitable for general receipts but doesn’t provide fine‑grained per‑order control and complicates reconciliation.

Can I reconcile without webhooks?

You can use polling as a fallback, but reliable webhooks are essential for low‑latency confirmations. Use signature verification, retries with backoff and idempotency. Polling should have strict limits and only reprocess mapped pending items.

How to avoid double settlement of the same payment?

Implement idempotency with unique keys such as TXID or E2E ID. Before applying a state change, check if it was already processed. Keep structured logs, deduplication and an exceptions queue for manual resolution.

Can refunds (returns) be automated in PIX?

Yes. Define the authorization flow, log the reason and trigger the gateway request. Update the order in two stages: refund initiated and refund completed. Every refund needs an audit trail and reconciliation in the financial report.

How long does implementation take?

It depends on scope, chosen gateway, store platform and ERP integrations. Projects with well‑defined APIs and logs typically move faster. The safest path starts with a technical diagnosis and a proof of concept.

Does this work with any e‑commerce platform?

Generally, yes. The technical design assumes a store API, gateway events and ERP integration. Some plugins limit customization, so auxiliary services for webhooks, reconciliation and reporting may be needed.

Want a robust, reconciled PIX checkout?

Tell us about your current flow, bottlenecks and goals. We’ll assess your checkout, gateway events and financial routines to propose a PIX integration with reconciliation that reduces errors and simplifies closing the books.

Discuss PIX integration