PIX com QR e Copia-cola

Visão Geral

Quando o método de pagamento selecionado é PIX, o sistema gera automaticamente um QR code dinâmico e o payload "Copia e Cola". Após a confirmação do pagamento, o pedido é fechado automaticamente via webhook ou confirmação manual.

Característica	Detalhe
Tipo	PIX dinâmico (EMV QR Code)
Geração	No momento de confirmar o pagamento
Chave PIX	Configurada em Admin → Configurações → PIX
Validade do QR	10 minutos (padrão)
Frontend	`frontend-react/src/views/pdv/PaymentModal.tsx`

Localização

Camada	Arquivo
Modal PDV	`frontend-react/src/views/pdv/PaymentModal.tsx`
API Order (cria pedido + QR)	`backend/src/orders/orders.service.ts`
Checkout cliente	`frontend-react/src/views/customer/CheckoutView.tsx`
Configuração PIX	`backend/src/tenants/schemas/tenant.schema.ts` — `pixKey`, `pixMerchantName`

Pré-requisito

O tenant precisa ter configurada a chave PIX e o nome do comerciante:

Admin → Configurações → PIX:

Campo	Descrição
`pixKey`	Chave PIX (CPF, CNPJ, e-mail, telefone ou chave aleatória)
`pixMerchantName`	Nome que aparece no app do cliente (até 25 caracteres)
`pixCity`	Cidade do estabelecimento
`pixExpirationMinutes`	Validade do QR code (default: 10 min)

Fluxo no PDV

1. Atendente seleciona PIX no PaymentModal
2. Confirma → POST /t/:slug/orders (ou /orders/:id/process-payment)
3. API retorna { pixPayload, pixQrCodeBase64 }
4. Modal exibe:
   - Imagem do QR code (PNG Base64)
   - Campo "Copia e Cola" com botão de copiar
5. Cliente escaneia ou copia o código no app bancário
6. Cliente paga
7. Atendente clica "Pagamento Confirmado" para fechar manualmente

Fluxo no Cardápio QR (cliente)

1. Cliente escolhe PIX no checkout
2. POST /t/:slug/orders com paymentMethod: 'pix'
3. API retorna pedido com pixPayload + pixQrCodeBase64
4. Checkout exibe QR code + copia-cola
5. Cliente paga no app bancário
6. Cliente é redirecionado para tela de tracking

Campos no Pedido

Quando o pagamento foi feito por PIX, o pedido armazena:

Campo	Descrição
`pixPayload`	Payload EMV "Copia e Cola" completo
`pixQrCodeBase64`	Imagem PNG do QR code em Base64
`pixKey`	Chave usada (snapshot do momento da criação)

Geração do Payload PIX (EMV)

O backend gera o payload seguindo o padrão EMV QR Code para pagamentos instantâneos Banco Central:

000201                    ← payload format indicator
010212                    ← ponto de iniciação estático/dinâmico
26XX0014br.gov.bcb.pix    ← merchant account information
5204xxxx                  ← MCC
5303986                   ← moeda BRL
54XXXXXX                  ← valor
5802BR                    ← país
59XXXX                    ← nome do comerciante
60XXXX                    ← cidade
62XX                      ← additional data field
6304XXXX                  ← CRC16

Recibo Digital

Após o pagamento, o cliente pode acessar o recibo em:

GET /t/:slug/orders/:orderNumber/receipt

O recibo inclui o valor, data/hora, chave PIX de destino e comprovante QR code.

Permissões

Ação	Role mínimo
Configurar chave PIX	`admin`
Processar pagamento PIX	`staff`
Ver payload PIX de pedido	`staff`

PIX com QR e Copia-cola ​

Visão Geral ​

Localização ​

Pré-requisito ​

Fluxo no PDV ​

Fluxo no Cardápio QR (cliente) ​

Campos no Pedido ​

Geração do Payload PIX (EMV) ​

Recibo Digital ​

Permissões ​

Relacionados ​