Skip to navigation

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.

Enabled per tenant

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

┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────────┐
│ 1. Generate │ │ 2. Confirm │ │ Debtor │ │ Webhook │
│ blocked QR │ ───► │ charge │ ───► │ Pays QR │ ───► │ qrcode.paid │
└─────────────┘ └──────────────┘ └─────────────┘ └─────────────┘
status BLOCKED status ACTIVE

Step 1: Generate the blocked QR

Request

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/location" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: {tenant_id}" \
-H "Content-Type: application/json" \
-d '{
"pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
"identifier": "table-12-night",
"message": "Table 12"
}'
FieldTypeRequiredDescription
pixKeystringYesPIX key of the receiving account (must be registered)
identifierstringRecommendedUnique identifier (up to 38 characters, charset [A-Za-z0-9._-]). When omitted, the API generates a UUID without hyphens. You confirm, look up and cancel by it
messagestringNoMessage shown to the payer (up to 140 characters)

Success Response (201 Created)

{
"txid": "table-12-night",
"emv": "00020101021226900014br.gov.bcb.pix2568qrcode.exemplo.com/cobv/9f1c2a7e3b5d4c6e8a0b1c2d3e4f5a6b5204000053039865802BR5914LOJA EXEMPLO6009SAO PAULO62070503***6304C3D4",
"type": "location",
"status": "BLOCKED",
"value": 0,
"message": "Table 12",
"description": "Table 12",
"identifier": "table-12-night",
"accountId": "{accountId}",
"pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
"allowChange": false,
"locationId": "9f1c2a7e-3b5d-4c6e-8a0b-1c2d3e4f5a6b"
}
FieldDescription
emvPIX Copy and Paste code. It can be printed already; payment is refused while status is BLOCKED
statusBLOCKED until confirmation
locationIdQR identifier at the settlement bank. Also accepted instead of identifier on confirmation

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

curl -X PUT "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/location/table-12-night/confirm" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: {tenant_id}" \
-H "Content-Type: application/json" \
-d '{
"value": 230.40,
"dueDate": "2026-11-01",
"debtor": {
"name": "João Souza",
"document": "12345678901"
}
}'

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)

{
"txid": "table-12-night",
"emv": "00020101021226900014br.gov.bcb.pix2568qrcode.exemplo.com/cobv/9f1c2a7e3b5d4c6e8a0b1c2d3e4f5a6b5204000053039865802BR5914LOJA EXEMPLO6009SAO PAULO62070503***6304C3D4",
"type": "location",
"status": "ACTIVE",
"value": 230.40,
"message": "Table 12",
"description": "Table 12",
"identifier": "table-12-night",
"accountId": "{accountId}",
"pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
"allowChange": false,
"createdAt": "2026-11-01T22:10:00Z",
"expiresAt": "2026-11-02T02:59:59Z",
"locationId": "9f1c2a7e-3b5d-4c6e-8a0b-1c2d3e4f5a6b",
"dueDate": "2026-11-01",
"daysAfterDueDate": 0,
"deduction": 0,
"discount": 0,
"interest": 0,
"penalty": 0,
"finalValue": 230.40,
"debtor": {
"name": "João Souza",
"document": "12345678901"
},
"receiverName": "LOJA EXEMPLO"
}

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.

{
"errorCode": "partner_rejected",
"message": "O liquidante recusou a operação.",
"docs": "https://docs.api.corpx.com/baas/guias/referencia/erros#partner_rejected",
"details": { "qrStatus": "BLOCKED" }
}

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

EventWhen
qrcode.location_generatedThe QR was generated blocked
qrcode.location_confirm_failedConfirmation was refused; the QR stays blocked
qrcode.createdConfirmation was accepted and the QR started accepting payment
qrcode.paidThe QR was paid

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

errorCodeHTTPCauseFix
missing_field400pixKey missing on generation; dueDate, debtor or the receiver missing on confirmationSend the required fields
invalid_document400debtor.document has neither 11 nor 14 digitsSend a valid CPF or CNPJ
invalid_field400Invalid terms (see due-date QR) or message over 140 charactersFix the terms
invalid_identifier400identifier outside the charset or over 38 charactersFix the identifier
feature_disabled403Product not enabled for the tenantAsk CorpX to enable it
not_found404No Location QR with that identifier/locationId on the accountCheck the identifier and the accountId
invalid_state409The QR is not a Location QR or is already confirmedLook up the QR before confirming
policy_denied422A dynamic QR policy rule refused the amountSee violations — Policies and Rules

Next Steps