To prevent duplication in a charge offering boleto and Pix, represent a single commercial obligation, maintain each instrument's identity, and confirm receipts on the server. Ensure that only one confirmation satisfies the order and releases fulfillment. Then track cancellation of the alternative instrument and reconcile any additional amount received. Hiding the QR code or barcode on screen is not enough to prevent a second payment.
The challenge arises when money and messages follow different paths. The customer may pay through one channel while the other still appears available. One confirmation may arrive after another even though it represents an earlier payment. The integration needs to explain these events without duplicating delivery, deleting receipts, or refunding the wrong amount.
This guide presents an architectural proposal and a wholly fictional R$ 249 case. The suggested internal states are not endpoint names or announced AZPay features. Regulatory references were consulted on October 22, 2026; product availability and operational procedures need to be confirmed with the contracted participant.
What does boleto with Pix mean, and what changes with hybrid billing?
Boleto with Pix usually describes a presentation offering a barcode and a QR code to pay the same obligation. The Central Bank's announcement about boleto modernization (opens in a new tab ↗) distinguishes this possibility from the creation of dynamic boleto. Having a QR code therefore does not automatically make a boleto dynamic or turn two independent charges into a coordinated integration.
BCB Resolution 587/2026 (opens in a new tab ↗), dated September 18, provides specific rules for hybrid billing. Under Article 5, the relevant changes take effect on February 1, 2027. In October 2026, it is necessary to distinguish solutions already offered in the market from those future rules.
The planned Article 11-AA restricts this modality to Pix Cobrança with a due date combined with a standard or dynamic boleto not linked to a financial asset. Offering it is optional; the receiving PSP must be the institution issuing the boleto. The text also requires consistency between payment schemes and Pix cancellation in the specified circumstances. These conditions prevent treating every QR-and-boleto combination as equivalent.
When contracting or reviewing an integration, ask for evidence of how it works today and how it will meet the applicable effective date. The product's commercial name alone does not demonstrate a link between instruments, coordinated cancellation, or exception handling. The controls below are an engineering proposal to preserve business facts and decisions, not a replacement for the regulation or the participant's contract.
One obligation, two instruments, and receipts with their own identities
The obligation is what the customer owes: for example, R$ 249 for a specific order. The boleto and Pix charge are instruments related to that obligation. A receipt is a verified financial fact. These three layers need to remain distinguishable when repeated messages or closely timed payments arrive.
A conceptual model can use order_id for the order, obligation_id for the obligation, and one external reference per instrument. The names are illustrative. If an order can generate installments, additional charges, or replacement charges, order_id alone does not identify which obligation is being satisfied. Also record amount, currency, due date, and the version of the commercial terms.
For Pix, preserve the relationship between the charge, txid, and the receipt's EndToEndId. For boleto, retain the reference recognized by the issuer within the contract's context, without assuming that an isolated identifier is globally unique. The official Pix API 2.10.0 specification (opens in a new tab ↗) is a reference for Pix objects; the PSP's commercial API may expose a different structure.
Each instrument should point to the same obligation, but every receipt needs its own identity. Two notifications for the same Pix payment are repeated messages. A Pix payment and a boleto that were both actually paid are two different financial facts. Deduplicating them as if they were the same event would hide the excess amount.
What evidence allows the obligation to be marked as paid?
Displaying a boleto, generating a QR code, or receiving a customer's payment receipt should not, by itself, trigger automatic discharge of the obligation. The server needs verifiable provider confirmation according to the channel's contract. Record the evidence source, external identifier, amount, and timestamps available for investigation.
Also distinguish the payment time, the time the provider confirmed it, and the time your application received the information. An event arriving first does not prove its corresponding payment happened first. That distinction matters when deciding which occurrence requires correction and explaining a complaint to the participant.
The Central Bank explains that payment through a Pix QR code is instant and does not follow boleto business-day clearing windows in its guidance on documents with QR codes (opens in a new tab ↗). This does not define a universal notification deadline for your application. Confirm the times, cutoffs, and query methods of each contracted service.
In practice, webhooks and queries should converge on the same financial record. The integration does not gain two payments because it discovered one receipt through two paths. The article on Pix charges, confirmation, and refunds explores these identities without mixing them with order state.
How should obligation and instrument states be separated?
A plausible state machine starts with an open obligation. When insufficient or conflicting evidence arrives, it can move to verification. Valid confirmation for the full amount allows an allocation to be recorded and the obligation to become paid. If the order is commercially canceled, the obligation can be closed without payment while preserving the ability to recognize money arriving afterward.
In parallel, each instrument tracks its own lifecycle. It may be being issued, available for payment, cancellation requested, cancellation confirmed, or payment confirmed. States should be adapted to the PSP's actual capabilities. A cancellation request must not silently be translated into completed cancellation.
An additional receipt does not need to reopen a paid obligation. It creates a financial exception linked to the same history. Similarly, refunding the excess does not undo the payment that remains correctly allocated to the order. Avoid reducing this entire situation to one status field.
Keep three questions separate: is the obligation satisfied? Does each instrument still accept payment according to external evidence? Is there money received whose allocation remains unresolved? Support can then explain that the order is paid and an additional receipt is being handled without contradicting finance.
How can you ensure a single discharge when two processes arrive together?
The decision to allocate a payment to the obligation must be atomic. If two consumers read open simultaneously and then update it to paid, both may trigger delivery. One proposal is to protect the transition with a transaction and a uniqueness constraint for the full allocation of that obligation. The design should account for the data model and its partial-payment policy.
Within that local transaction, record the already validated receipt, attempt the permitted allocation, and persist the commercial release message in an outbox. If the obligation is already satisfied, record the new receipt as an exception; do not discard the financial fact. A separate constraint should recognize the same external transaction when it reappears through a query or webhook.
The fulfillment consumer also needs to recognize the same command. The outbox lets an interrupted publication resume, but it does not automatically make inventory, tax document issuance, or shipping idempotent. The release key should correspond to the intended delivery for that obligation, not the channel that notified payment.
External cancellation remains asynchronous relative to the local transaction. Do not hold a database transaction open while waiting for the PSP API. Record the pending action and process it with recovery. This separation guarantees a single local commercial decision while financial coordination continues to be tracked.
Idempotency in payment APIs protects repeated commands within the documented scope. It does not make a key used for boleto prevent an independent Pix payment. In billing with alternatives, obligation identity and the allocation rule are additional controls.
Fictional case: a R$ 249 order receives both Pix and boleto payments
Consider a fictional store with a R$ 249 order, without interest, discounts, or fees in this example. The obligation has two linked options. The customer pays the boleto and, not noticing confirmation, also completes the Pix payment. The application receives the Pix notification first; boleto confirmation arrives later. This sequence illustrates a possible exception, not a product's universal behavior.
After verifying the R$ 249 Pix payment, the application records receipt and satisfies the obligation once. The delivery command is persisted with a unique identity. It then records the action needed to withdraw the alternative option according to the participant's mechanism. The interface now shows confirmed payment without offering a new charge.
When the boleto event arrives, the integration first determines whether it confirms a distinct payment. If it is only an already processed message, it records the repetition without another effect. If a second R$ 249 receipt is confirmed, it preserves that fact and opens an excess-payment case. The order still has one delivery, not two. Duplication is an occurrence to investigate; it does not, by itself, prove fraud.
The gross amounts are R$ 498 received, R$ 249 allocated to the obligation, and R$ 249 requiring resolution. Do not turn R$ 498 into revenue from a R$ 249 sale. Do not artificially change the Pix record to R$ 0 to make the total look correct either. The difference needs a documented disposition.
Before correcting it, the team checks the participant's financial chronology. Notification order alone does not determine which payment is retained and which movement needs resolution. Treatment depends on confirmed facts, the applicable rule, participant responsibilities, and the available procedure. The application should track resolution, including any refund already made externally. If the initially allocated Pix payment needs to be returned and the boleto retained, record a reallocation with an adjustment trail. The obligation remains satisfied, delivery is not repeated, and the original allocation remains auditable.
If R$ 249 is actually refunded and there are no other movements, the gross closing balance will be R$ 498 received minus R$ 249 refunded, leaving R$ 249 retained. The case closes only when external evidence and local entries explain that outcome. Requesting a refund is not yet proof of completion.
Why does canceling the alternative instrument not end the investigation?
The cancellation action needs a persisted intent, stable identity, outcome, and a query mechanism where available. If the response is lost, the local state should reflect uncertainty. A new call is safe only within the documented guarantees for that operation; generating another reference without investigation can make recovery harder.
There may also be a race between payment and cancellation. The application may discover financial success before it can confirm withdrawal of the other option. Rather than promising an invented protection window, treat the interval as an observable situation: track the pending action, its waiting time, and any conflicting event.
If the PSP offers coordination between instruments, check which event proves that coordination and how exceptions are reported. If evidence is insufficient, the operation needs to query and escalate the discrepancy. Removing the checkout button remains useful for guiding the customer, but it does not control a copy of the boleto or QR code that has already left your interface.
The design of idempotent webhooks helps receive, validate, and process repeated messages. Here, add the link between instruments so a valid event is not applied to the wrong obligation or treated as authorization for a second delivery.
How should refunds be handled without creating a third improper movement?
A duplication case should identify which receipt will be corrected, the pending amount, and who executes the action. Before initiating any refund, check movements already performed by the participant and requests still in progress. Support and automation should not operate independent controls over the same excess.
For the specific case of a Pix payment settled after the obligation was already paid by boleto, the planned Article 41-A, paragraph 3, of BCB Resolution 587/2026 (opens in a new tab ↗) assigns the receiving PSP responsibility for a full refund from its own funds within 24 hours. This provision also takes effect on February 1, 2027. Do not generalize it to every duplicate payment or an earlier date.
In the proposed application model, a refund has its own identity and a link to the original receipt. If a timeout occurs, preserve that identity and investigate the result. Do not generate a second refund just because the operator received no response. While the first remains indeterminate, it must continue to count toward the amount reserved for correction.
Also distinguish refunding an excess payment from refunding the purchase. The customer may receive the additional payment back and later cancel the order for another reason. These are two different intents with their own bases and limits. The history needs to explain both without refunding the same receipt twice or confusing the excess with a reduction in the sale.
How do you close reconciliation for billing with alternatives?
The routine should compare the obligation, issued instruments, receipts, allocations, cancellation requests, and refund movements. Match by identity and use amount, currency, and time as additional checks. Two R$ 249 charges on the same day do not necessarily belong to the same order.
A useful invariant for the simple case is: total received minus total refunded must be explained by allocated amounts and amounts still requiring resolution. In the example, R$ 498 minus R$ 0 equals R$ 249 allocated plus R$ 249 pending. After the refund is confirmed, R$ 498 minus R$ 249 equals the allocated R$ 249.
Fees, adjustments, and calendar differences should have separate movements. They do not change the payer's identity or justify erasing the excess. The payment ledger provides the internal trail; reconciliation between sale, capture, and settlement explains how to compare it with external sources.
Create separate queues for receipts with no known obligation, amount discrepancies, alternative instruments with unconfirmed cancellation, and unresolved excess. Every case needs an owner, a next action, and evidence of closure. Exception age matters as much as count: a small total can hide a customer who has been waiting a long time for a solution.
What if the order expired or the amount does not match?
Expiring the order does not erase a later receipt. One proposal is to record the incoming funds and suspend the commercial decision until inventory availability, sale conditions, and resolution policy are checked. Automatically reopening an order may be inappropriate when price, delivery, or reservation has already changed.
If the amount received is lower or higher than expected, do not silently apply the full-payment example's rule. First validate the interest, late fee, discount, and due date reported by the participant. Then classify the difference. Misinterpreting the amount rule can look like duplication or underpayment without a second payment existing.
When the product and business allow partial payments, replace the single full-allocation constraint with transactional control over allocated amounts. Do not accept concurrent sums above the obligation's balance. This adaptation requires its own design; the R$ 249 example should not be copied as though it covers installments, additional charges, and every boleto modality.
What should you test before offering both paths to the customer?
Test repeated Pix notifications, repeated boleto confirmations, and the same receipt discovered through both a query and a webhook. The expected result is one financial record per external fact and a single release for the fully paid obligation. Then force both distinct receipts to arrive simultaneously: both must remain in the history, with only one allocated and the excess routed for handling.
Simulate a failure after persisting discharge and before publishing delivery. Recovery should resend the command without repeating the commercial effect. Also simulate interruptions before and after requesting cancellation. The queue needs to resume the action and recognize the external result without confusing request with completion.
Reverse notification order and preserve financial timestamps distinct from arrival times. Test payment after expiration, unknown references, mismatched amounts, and temporarily unavailable queries. None of these cases should release delivery merely because amounts look alike or cause the system to ignore confirmed money.
Finally, simulate a refund in progress, a lost response, and resolution already performed by the participant. Support should find the same case used by automation. Acceptance means reconstructing received, allocated, refunded, and pending amounts from evidence without relying on the on-call person's memory.
Which integration contract needs to be clear?
Before enabling the journey, confirm with the participant how instruments are linked, which query proves payment, which references appear in notifications, how the alternative is canceled, and how conflicting payments are handled. Also document intermediate states, recovery procedures, and the escalation channel.
In the interface, explain that the paths are alternatives for the same obligation. After confirmation, show the known state and support guidance when there is a discrepancy. Avoid instructing the customer to pay again while a receipt is under verification. Communication should reflect what the server can prove.
To assess an AZPay integration, consult Dev Central and confirm the intended service's contract. This guide does not claim that hybrid boleto is available on the platform. Its proposal is to make the engineering decision verifiable: an identified obligation, preserved financial facts, a single commercial release, and traceable resolution for any additional amount.