> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# 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](/baas/guias/receber/qr-code-com-vencimento): 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

```bash
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"
  }'
```

| Field        | Type   | Required    | Description                                                                                                                                                      |
| ------------ | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pixKey`     | string | Yes         | PIX key of the receiving account (must be registered)                                                                                                            |
| `identifier` | string | Recommended | Unique 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 |
| `message`    | string | No          | Message shown to the payer (up to 140 characters)                                                                                                                |

### Success Response (201 Created)

```json
{
  "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"
}
```

| Field        | Description                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `emv`        | PIX Copy and Paste code. It can be printed already; payment is refused while `status` is `BLOCKED` |
| `status`     | `BLOCKED` until confirmation                                                                       |
| `locationId` | QR identifier at the settlement bank. Also accepted instead of `identifier` on confirmation        |

> **Note**
>
> 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

```bash
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](/baas/guias/receber/qr-code-com-vencimento#body-parameters):
`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)

```json
{
  "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](/baas/guias/conta/timeline) as
`qrcode.location_confirm_failed`.

```json
{
  "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](/baas/guias/receber/qr-code-com-vencimento#step-3-receive-the-webhook).

## Timeline

| Event                            | When                                                           |
| -------------------------------- | -------------------------------------------------------------- |
| `qrcode.location_generated`      | The QR was generated blocked                                   |
| `qrcode.location_confirm_failed` | Confirmation was refused; the QR stays blocked                 |
| `qrcode.created`                 | Confirmation was accepted and the QR started accepting payment |
| `qrcode.paid`                    | The 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

| `errorCode`          | HTTP | Cause                                                                                                                        | Fix                                                                         |
| -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `missing_field`      | 400  | `pixKey` missing on generation; `dueDate`, `debtor` or the receiver missing on confirmation                                  | Send the required fields                                                    |
| `invalid_document`   | 400  | `debtor.document` has neither 11 nor 14 digits                                                                               | Send a valid CPF or CNPJ                                                    |
| `invalid_field`      | 400  | Invalid terms (see [due-date QR](/baas/guias/receber/qr-code-com-vencimento#common-errors)) or `message` over 140 characters | Fix the terms                                                               |
| `invalid_identifier` | 400  | `identifier` outside the charset or over 38 characters                                                                       | Fix the identifier                                                          |
| `feature_disabled`   | 403  | Product not enabled for the tenant                                                                                           | Ask CorpX to enable it                                                      |
| `not_found`          | 404  | No Location QR with that `identifier`/`locationId` on the account                                                            | Check the identifier and the accountId                                      |
| `invalid_state`      | 409  | The QR is not a Location QR or is already confirmed                                                                          | Look up the QR before confirming                                            |
| `policy_denied`      | 422  | A dynamic QR policy rule refused the amount                                                                                  | See `violations` — [Policies and Rules](/baas/guias/autenticacao/politicas) |

## Next Steps

* [Due-date QR Code](/baas/guias/receber/qr-code-com-vencimento) - Due-date charge issued in one call
* [Webhooks](/baas/guias/conta/webhooks) - Configure notifications