Skip to navigation

Guia de Pix Location

Este guia explica como gerar um QR Code PIX antes de saber o valor e o devedor da cobrança, e liberá-lo para pagamento depois.

Visão Geral

No Pix Location o QR é gerado bloqueado: o código copia e cola já existe e pode ser impresso, colado num produto ou enviado, mas o pagamento é recusado até você confirmar a cobrança com valor, vencimento e devedor. É indicado para:

  • Etiquetas e embalagens - QR impresso antes do pedido existir
  • Comandas e contas - QR na mesa, valor definido no fechamento
  • Faturas pré-impressas - Layout pronto, valor fechado depois

Depois de confirmado, o QR se comporta como um QR Code com vencimento: tem vencimento, encargos e o mesmo webhook qrcode.paid.

Produto habilitado por tenant

O Pix Location precisa estar habilitado no seu tenant. Sem a habilitação, a geração e a confirmação respondem 403 feature_disabled. Peça a ativação ao time da CorpX.

Fluxo de Integração

┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────────┐
│ 1. Gerar QR │ │ 2. Confirmar │ │ Devedor │ │ Webhook │
│ bloqueado │ ───► │ cobrança │ ───► │ Paga QR │ ───► │ qrcode.paid │
└─────────────┘ └──────────────┘ └─────────────┘ └─────────────┘
status BLOCKED status ACTIVE

Passo 1: Gerar o QR bloqueado

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": "mesa-12-noite",
"message": "Mesa 12"
}'
CampoTipoObrigatórioDescrição
pixKeystringSimChave PIX da conta recebedora (deve estar cadastrada)
identifierstringRecomendadoIdentificador único (máximo 38 caracteres, charset [A-Za-z0-9._-]). Se omitido, a API gera um UUID sem hifens. É por ele que você confirma, consulta e cancela
messagestringNãoMensagem exibida ao pagador (máximo 140 caracteres)

Resposta de Sucesso (201 Created)

{
"txid": "mesa-12-noite",
"emv": "00020101021226900014br.gov.bcb.pix2568qrcode.exemplo.com/cobv/9f1c2a7e3b5d4c6e8a0b1c2d3e4f5a6b5204000053039865802BR5914LOJA EXEMPLO6009SAO PAULO62070503***6304C3D4",
"type": "location",
"status": "BLOCKED",
"value": 0,
"message": "Mesa 12",
"description": "Mesa 12",
"identifier": "mesa-12-noite",
"accountId": "{accountId}",
"pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
"allowChange": false,
"locationId": "9f1c2a7e-3b5d-4c6e-8a0b-1c2d3e4f5a6b"
}
CampoDescrição
emvCódigo PIX Copia e Cola. Já pode ser impresso; o pagamento é recusado enquanto status for BLOCKED
statusBLOCKED até a confirmação
locationIdIdentificador do QR no liquidante. Também aceito no lugar do identifier na confirmação

O qrcodeId dos webhooks continua sendo o txid. O locationId é outro identificador e só aparece nas respostas do QR Location.

Passo 2: Confirmar a cobrança

A confirmação define os termos da cobrança e libera o pagamento.

Request

curl -X PUT "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/qr-code/location/mesa-12-noite/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"
}
}'

O path aceita o identifier usado na geração ou o locationId. O body tem os mesmos termos do QR Code com vencimento: value, dueDate e debtor obrigatórios; daysAfterDueDate, deduction, discount, interest, penalty, finalValue, receiverName e message opcionais, com as mesmas regras (vencimento em até 365 dias, no máximo 2 casas decimais). A chave PIX e o identifier são sempre os da geração.

Resposta de Sucesso (200 OK)

{
"txid": "mesa-12-noite",
"emv": "00020101021226900014br.gov.bcb.pix2568qrcode.exemplo.com/cobv/9f1c2a7e3b5d4c6e8a0b1c2d3e4f5a6b5204000053039865802BR5914LOJA EXEMPLO6009SAO PAULO62070503***6304C3D4",
"type": "location",
"status": "ACTIVE",
"value": 230.40,
"message": "Mesa 12",
"description": "Mesa 12",
"identifier": "mesa-12-noite",
"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"
}

O emv não muda: é o mesmo QR da geração, agora liberado.

Quando a confirmação é recusada

Se o liquidante recusar a confirmação, a resposta traz o erro e details.qrStatus = "BLOCKED": o QR continua bloqueado e você pode confirmar de novo com os dados corrigidos. A recusa também aparece na linha do tempo da transação como 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" }
}

Um QR já confirmado, ou com outra confirmação em andamento, não aceita nova confirmação (409 invalid_state). Se o liquidante não responder e não for possível conferir o estado do QR, o erro vem sem details.qrStatus: consulte o QR antes de confirmar de novo.

Passo 3: Consultar, cancelar e receber o pagamento

Consulta e cancelamento são os mesmos do QR dinâmico, pelo identifier (GET .../pix/qr-code/lookup?identifier= e DELETE .../pix/qr-code?identifier=). Antes da confirmação o lookup devolve status: "BLOCKED".

O pagamento chega como qrcode.paid com data.type = "location" e data.amount igual ao valor efetivamente pago. Sem pagamento até expiresAt, chega qrcode.expired. Veja o exemplo de webhook do QR com vencimento.

Linha do tempo

EventoQuando
qrcode.location_generatedO QR foi gerado bloqueado
qrcode.location_confirm_failedA confirmação foi recusada; o QR segue bloqueado
qrcode.createdA confirmação foi aceita e o QR passou a aceitar pagamento
qrcode.paidO QR foi pago

Permissões

As duas rotas usam o mesmo escopo do QR dinâmico, qrcode.manage (ou api2/write). No painel do integrador, gerar e confirmar exigem a permissão Emitir QR code com vencimento e Pix Location.

Erros Comuns

errorCodeHTTPCausaSolução
missing_field400pixKey ausente na geração; dueDate, debtor ou o recebedor ausente na confirmaçãoEnvie os campos obrigatórios
invalid_document400debtor.document sem 11 nem 14 dígitosEnvie um CPF ou CNPJ válido
invalid_field400Termos inválidos (ver QR com vencimento) ou message acima de 140 caracteresAjuste os termos
invalid_identifier400identifier fora do charset ou acima de 38 caracteresAjuste o identificador
feature_disabled403Produto não habilitado no tenantPeça a ativação à CorpX
not_found404Nenhum QR Location com esse identifier/locationId na contaVerifique o identificador e o accountId
invalid_state409O QR não é Location ou já foi confirmadoConsulte o QR antes de confirmar
policy_denied422Uma regra de política de QR dinâmico recusou o valorVeja violations — Políticas e Regras

Próximos Passos