Pix Location Guide
This guide explains how to generate a PIX QR Code before you know the amount and the debtor of the charge, and release it for payment later.
Overview
With Pix Location the QR is generated blocked: the copy-and-paste code already exists and can be printed, stuck on a product or sent, but payment is refused until you confirm the charge with amount, due date and debtor. It fits:
- Labels and packaging - QR printed before the order exists
- Tabs and bills - QR on the table, amount set at closing
- Pre-printed invoices - Layout ready, amount closed later
Once confirmed, the QR behaves like a
due-date QR Code: it has a due
date, charges and the same qrcode.paid webhook.
Pix Location must be enabled for your tenant. Without it, generation and
confirmation return 403 feature_disabled. Ask the CorpX team to enable it.
Integration Flow
Step 1: Generate the blocked QR
Request
Success Response (201 Created)
The webhook qrcodeId is still the txid. locationId is a different
identifier and only appears in Location QR responses.
Step 2: Confirm the charge
Confirmation sets the charge terms and releases payment.
Request
The path accepts the identifier used at generation or the locationId. The
body has the same terms as the due-date QR Code:
value, dueDate and debtor are required; daysAfterDueDate, deduction,
discount, interest, penalty, finalValue, receiverName and message
are optional, with the same rules (due date within 365 days, at most 2 decimal
places). The PIX key and the identifier are always the ones from generation.
Success Response (200 OK)
The emv does not change: it is the same QR from generation, now released.
When confirmation is refused
If the settlement bank refuses the confirmation, the response carries the
error and details.qrStatus = "BLOCKED": the QR stays blocked and you can
confirm again with corrected data. The refusal also shows up in the
transaction timeline as
qrcode.location_confirm_failed.
A QR that is already confirmed, or has another confirmation in progress,
does not accept a new confirmation (409 invalid_state). If the settlement
bank does not answer and the QR state cannot be checked, the error comes
without details.qrStatus: look the QR up before confirming again.
Step 3: Look up, cancel and receive payment
Lookup and cancellation are the same as for the dynamic QR, by identifier
(GET .../pix/qr-code/lookup?identifier= and DELETE .../pix/qr-code?identifier=).
Before confirmation the lookup returns status: "BLOCKED".
Payment arrives as qrcode.paid with data.type = "location" and
data.amount equal to the amount actually paid. Without payment by
expiresAt, you receive qrcode.expired. See the
due-date QR webhook example.
Timeline
Permissions
Both routes use the same scope as the dynamic QR, qrcode.manage (or
api2/write). In the integrator dashboard, generating and confirming require
the Issue due-date and Pix Location QR codes permission.
Common Errors
Next Steps
- Due-date QR Code - Due-date charge issued in one call
- Webhooks - Configure notifications