To a user, Pix may look like a single action: scan a QR code, confirm in a banking app, and see the payment-complete screen. For the recipient's infrastructure, however, it involves a sequence of objects, identifiers, states, and events that must be modeled carefully.
A payment request, QR code, received Pix payment, txid, EndToEndId, refund, and webhook are not different words for the same thing. Each represents part of the flow. When an integration mixes these layers, problems arise: orders released too early, payments without matching orders, untraceable refunds, and repeated event processing.
Understanding the Pix lifecycle is particularly important because it is an instant payment method. That does not mean every surrounding architectural component is synchronous or that the application can depend on a single HTTP response.
Is Pix a transfer or a payment-request flow?
It may appear to users as an instant transfer, but a commercial integration normally needs a payment-request flow around the payment.
The business must represent the intent to collect, amount, expiration, and business reference, then confirm whether the corresponding Pix payment was actually received.
The payment itself is a financial event. The payment request is the commercial context that prepares and organizes that event.
Separating them is essential to reconciling orders and receipts.
What is a Pix payment request?
A payment request is an object representing a request for payment, with rules and information that allow a QR code to be generated or associated with it.
Depending on the case, it may be payable immediately or have a due date, along with attributes specific to the selected flow.
Architecturally, the request answers something like “what do we want to receive?”
The received Pix payment answers “what actually settled?”
The application should not confuse intent with financial fact.
What is txid?
The txid is an identifier associated with the payment request and plays an important role in correlating the recipient's context with the received Pix payment.
It should not be treated as merely a visual detail in the QR code.
Used properly, it helps connect the request, order, confirmation, and reconciliation.
The business still needs its own internal identifiers, but txid becomes an important bridge within the Pix ecosystem.
Is txid the same as EndToEndId?
No.
The txid relates to the request and the context defined in the recipient's flow.
EndToEndId identifies the Pix payment actually processed in the system and accompanies the financial event.
This separation is useful because a payment request is created before payment occurs, whereas the end-to-end identifier is associated with the executed transaction.
For reconciliation and refunds, knowing which identifier belongs to which layer avoids considerable confusion.
What is a static QR code?
A static QR code directly represents certain payment data in its payload and can be reused depending on the use case.
It can be useful in simple situations, such as repeated receipts at a physical location, but provides less dynamic control over each commercial intent.
If several sales use the same QR code, the application needs another strategy to identify which payment belongs to which order.
Simpler generation can therefore mean more complex reconciliation.
What is a dynamic QR code?
A dynamic QR code allows the flow to point to payment-request information associated with a specific intent.
This makes it easier to control the amount, validity, reference, and request state.
For e-commerce and automated integrations, this model tends to be more natural because each order can have its own request and explicit correlation.
The QR code is only the payer's initiation mechanism. Business truth remains in the objects and events the application tracks.
Does a dynamic QR code guarantee payment?
No.
Generating a QR code does not mean receiving money.
The application must wait for evidence that an associated Pix payment was actually received.
The same principle applies to other payment methods: creating an intent does not complete the financial effect.
How does a payment request change state?
Payment requests have their own states.
A request may be active, removed by the recipient, or reach a completed state when a Pix payment associated with its txid is received under the applicable flow.
A completed request represents a different fact from a request that was merely created.
The business system must respond to the right event, not to the existence of a QR code.
Can a payment request be removed?
Yes. Subject to the applicable flow and rules, a still-valid request can be removed by the recipient.
This is useful when a customer changes their mind, an order expires, or the business decides that the intent should no longer be paid.
A completed request should not be treated as a disposable object, because an associated Pix payment must remain traceable.
After payment, the logic changes from “remove the request” to handling a refund when necessary.
Are expiration and removal the same thing?
Not exactly.
Expiration follows the time window defined for the request or the Pix product used.
Removal is a recipient action to invalidate a request that might otherwise remain available.
Both may prevent a new valid initiation, but their causes and transitions are different.
This difference matters for customer support and auditing.
What happens if the customer pays after the order expires?
This is one of the scenarios that most challenges an integration.
The commercial order may expire before the customer completes the journey in the payer app. Depending on the actual request state and initiation method, the application must be ready to handle a Pix receipt in a commercial context that has already changed.
The correct rule is not simply to ignore the money.
The system must recognize the receipt, correlate it as far as possible, and decide whether to reopen the order, create an operational exception, or initiate a refund according to business policy.
How do you confirm that a Pix payment was received?
Confirmation must come from evidence supplied by the recipient's PSP or integrated infrastructure.
This may arrive through an asynchronous notification or a query of received Pix payments using the available interfaces.
The application should not rely on the customer's browser returning to a success page.
The customer may close the screen, lose connectivity, or complete payment on another device.
The financial fact exists independently of the web session.
What role does a webhook play in Pix?
A webhook notifies the application when a relevant Pix event occurs.
This reduces the need to continuously query the PSP to find out whether a request was paid.
But a webhook should not be treated as a message that dictates state without validation.
Events may be resent. The application must process them idempotently and correlate them with the correct object.
Can a webhook arrive more than once?
Yes, and the system should assume duplicates are possible in any reliable asynchronous integration.
If the same event is delivered more than once, processing it again should not release two orders, credit a balance twice, or trigger two refunds.
The strategy normally combines event or transaction identifiers with idempotency controls.
What if the webhook never arrives?
A missing webhook should not make a Pix payment permanently invisible.
A reconciliation or query routine can discover payments not reflected locally because of delivery failures, outages, or processing bugs.
Webhooks speed synchronization. Reconciliation ensures completeness.
Depending exclusively on a notification weakens financial closing.
What does EndToEndId do in practice?
EndToEndId is an essential reference for the Pix payment that was actually processed.
It helps identify the transaction within the ecosystem and appears in later operations, including refunds.
For merchants, this means preserving the identifier alongside the payment request and internal financial entity.
Losing it makes future investigations harder.
How does a Pix refund work?
A refund is an operation associated with an original Pix payment.
The application identifies the received transaction and initiates a refund with its own refund identifier under the rules of the API in use.
One Pix payment may allow several refunds, provided the total returned complies with applicable limits and does not exceed the original amount.
This naturally creates the concept of a partial refund.
Is a refund the same as canceling a Pix payment?
No.
Once a Pix payment has actually been processed, there is no “undo” that erases the original transaction.
A refund is a new movement linked to the received Pix payment.
This distinction matters for history and accounting.
The original transaction continues to exist; the refund records the later reverse movement.
How does a partial refund work?
If a R$ 500 purchase needs only R$ 120 returned, the application can create a partial refund when the supported flow permits it.
The remaining amount stays associated with the original Pix payment.
The system should therefore not model only “refunded: yes or no.”
It must track the amount received, the amount already refunded, and the remaining amount eligible for return.
Can one Pix payment have multiple refunds?
Yes, within applicable rules and limits.
This possibility makes modeling even more important.
Each refund needs its own identity and state, while all remain linked to the original Pix payment.
Without that separation, a second refund may overwrite the first, or the application may lose track of the total already returned.
Does requesting a refund mean it is complete?
Not necessarily.
As with other financial operations, the application must distinguish a request from completion.
The flow may require a subsequent status query or update.
Immediately marking it “refunded” without confirmation can create a discrepancy between the system and the actual movement.
How do you avoid refunding more than was received?
The domain must calculate the amount still available to refund.
This calculation must account for all completed refunds and, depending on policy, in-progress operations reserving part of the amount.
Relying only on a customer-support form is insufficient.
The rule belongs in the financial layer that controls the object.
What is an immediate payment request?
An immediate payment request represents a flow in which payment is expected without the future due date typical of a due-date request.
It is common at checkout, at the point of sale, and in journeys where the customer is paying right now.
Even though it is “immediate,” creating the request, displaying the QR code, and receiving the Pix payment remain different events.
What is a payment request with a due date?
A request with a due date introduces different timing and commercial logic.
It may represent an obligation payable by a specific date and include rules that would not make sense in an instant checkout.
The application must choose the object appropriate to its use case rather than treating every Pix payment as the same flow.
When the goal is to collect successive billing cycles with prior authorization, see the authorization and cancellation in Pix Automático guide, which distinguishes that service from a one-off Pix request.
Is Pix always instant from the merchant's perspective?
The scheme was designed for instant payments, but what the application sees depends on integration, notification, and internal processing.
A Pix payment may be complete within the ecosystem and still take a few seconds to appear in the merchant's system if the webhook is delayed.
That interval is enough to create race conditions when checkout queries status as the event arrives.
The system therefore needs to be idempotent.
How do you handle a race condition between a query and a webhook?
Imagine checkout queries the request and discovers the completed payment at the exact moment the webhook arrives.
Two processes may try to mark the order as paid.
If the transition is not idempotent, the application may perform fulfillment actions twice.
The payment state and release command must support safe repetition.
Should the order have the same status as the Pix request?
No.
Orders and payment requests belong to different domains.
The request may be created while the order awaits payment. When the Pix payment arrives, the payment changes state and the order decides what to do: allocate inventory, grant access, start shipping, or take another action.
This separation allows refunds to be handled without necessarily confusing the order's commercial state.
What happens when the received amount is unexpected?
The architecture should treat this as an explicit exception.
Depending on the flow, the request may enforce a specific amount. In other contexts, particularly more open initiation methods, a business may receive a Pix payment whose amount does not match the expected order.
The system should not silently force a match.
It is better to record the event and route it to a handling rule or reconciliation.
How do you reconcile Pix?
Reconciliation starts with identifiers and amounts.
The internal payment request must connect to its txid. The received Pix payment must retain its EndToEndId, amount, and timestamps. The internal financial movement must point to these records.
The business can then identify which requests were paid, which Pix payments have no context, which refunds occurred, and which discrepancies remain open.
What is an orphan Pix payment?
It is a receipt the system cannot automatically associate with a known business intent.
This may happen because of missing references, parallel integrations, payments outside the expected flow, or operational inconsistencies.
The money must not be ignored.
Reconciliation must record and investigate it until the movement is classified.
How does Pix differ from cards in a state machine?
Cards often place authorization and capture at the center of their model.
Pix should not be forced to imitate it.
The journey is more natural when the application represents a payment request, waits for receipt, confirms the Pix payment, and then tracks any refunds.
A multi-method abstraction should share concepts such as intent, attempt, success, and refund without inventing capture where none exists.
How does Pix fit into a multi-PSP platform?
A payment layer can offer a consistent interface for creating requests, querying state, receiving events, and initiating refunds.
But it must preserve Pix-specific features, such as txid, EndToEndId, and the semantics of its payment requests.
A good abstraction reduces integration effort without erasing essential payment-method concepts.
What should be idempotent?
Creating operations with financial or commercial effects must be protected against accidental repetition.
Webhook processing, payment confirmation, fulfillment, and refunds are clear examples.
If an event is delivered twice, the system must recognize that it represents the same fact.
If an operator clicks “refund” twice, the financial layer should not execute two independent refunds without explicit intent.
How do you handle a timeout when creating a request?
The application needs to know whether the call failed before or after the PSP created the object.
When the result is uncertain, immediately creating another request may duplicate the intent.
Idempotent identifiers and subsequent queries help resolve this ambiguity.
The principle is the same as with other financial APIs: no response does not prove no effect.
How do you handle a refund timeout?
With even greater care, because a financial effect is involved.
If the request was sent and the response lost, repeating it without checking state may create another refund, depending on how the integration uses identifiers.
The refund identifier must remain stable for that intent, and the system must verify the outcome before creating another operation.
How do you observe a Pix operation?
Useful metrics include time from creation to payment, expiration rate, orphan payments, webhook delays, correlation failures, refunds, amount discrepancies, and latency of the APIs involved.
It is also important to distinguish payer problems, PSP problems, and problems in your own application.
Without this distinction, every incomplete payment becomes a “Pix failure.”
What should not go into logs?
Observability should not become indiscriminate collection of sensitive data.
The team needs to record identifiers, states, timings, normalized outcomes, and information necessary for investigation, respecting data minimization and security policies.
Complete raw payloads are rarely the best permanent strategy.
Does Pix need an “awaiting payment” screen?
In e-commerce, usually yes.
The experience must make clear that displaying a QR code does not mean payment is confirmed.
The interface may update status automatically when the event arrives or poll periodically within reasonable limits.
What matters is that the frontend reflects the financial truth known by the backend.
Can the browser be the source of truth?
No.
Confirmation must exist on the server.
The browser is only a presentation interface and may disappear at any moment.
If an application relies on customer action after payment to record success, it will inevitably miss events.
How do you avoid fulfilling the same order twice?
The “payment confirmed” transition must be treated as an idempotent event.
Even if a webhook, polling, and a manual query discover the same Pix payment, they must all converge on one commercial effect.
This can be implemented with state controls, a unique key, and a database transaction.
When boleto and Pix provide paths to settle the same obligation, the instruments must be coordinated and additional receipts handled. The boleto with Pix and duplicate-payment prevention guide develops this case, including cross-cancellation and reconciliation.
How does Pix change checkout design?
In many cases, it clearly separates devices: the customer shops on a desktop and pays on a phone.
This means a browser redirect is insufficient for confirmation.
Checkout must be state- and event-driven.
The page simply observes the backend and presents what it knows.
How should abandonment be handled?
If a user generates a QR code and never pays, the request must expire or be removed according to the flow's rules.
The business can measure abandonment to improve UX, but should not confuse request generation with a completed financial attempt.
This also matters for conversion metrics: the denominator must be clearly defined.
How do you handle a refund after an order is canceled?
First, confirm that a Pix payment was received and how much remains refundable.
Then create the refund linked to the correct transaction.
The commercial order may change before or after the refund, but the financial operation needs its own lifecycle.
Separating the domains prevents order cancellation from erasing evidence of money already received.
What does Brazil's central bank standardize, and what does the PSP abstract?
The Pix ecosystem has regulations, manuals, and technical interfaces defined by Banco Central do Brasil and the scheme's participants.
PSPs may offer their own APIs that encapsulate some of this complexity for merchants.
Endpoint and object names visible to a merchant may therefore vary even when the underlying infrastructure follows Pix.
A platform must understand this difference to avoid confusing a PSP contract with a universal scheme concept.
How do you design a robust Pix domain?
Start by representing the collection intent, external payment request, received Pix payment, and refund as related but distinct entities.
Preserve txid and EndToEndId in the correct contexts.
Model intermediate states. Treat webhooks as repeatable events. Use queries and reconciliation to recover missed information. Control refunded amounts.
This design looks more elaborate than simply storing “pix_status.” In production, it reduces exceptions.
What is the difference between a payment request, a Pix payment, and a refund?
The payment request represents what the recipient intends to receive.
The Pix payment represents the payment actually processed.
A refund represents a later movement linked to the original Pix payment.
A QR code is an initiation mechanism, not the payment itself.
A webhook is a notification mechanism, not the exclusive source of truth.
These distinctions form the basis of a reliable integration.
Instant Pix still requires architecture
The scheme's speed does not eliminate states, events, or distributed failures.
On the contrary: when money changes state within seconds, the application must react correctly without relying on assumptions.
A robust implementation distinguishes requests from payments, preserves identifiers, processes events idempotently, reconciles missing information, and treats refunds as separate financial operations.
That is what turns a working QR code into reliable payment infrastructure.