Pagamento com QR Code

Este guia explica como realizar pagamentos com QR Code em um POS Integrado. Os pagamentos com QR Code usam a mesma operação Sale, com SaleType definido como QR code. O comportamento é idêntico em conexões USB e Rede.

O que é um pagamento com QR Code

Um pagamento com QR Code é uma venda em que o cliente escaneia um QR Code exibido no POS. Ele usa uma carteira (wallet) ou um aplicativo compatível. O sistema de automação envia uma requisição Sale com SaleType definido como QR code (ou enum equivalente). O terminal exibe o QR Code e aguarda o cliente escanear e aprovar. Em seguida, ele retorna a mesma estrutura de resposta de uma venda com cartão, com os campos específicos de cartão omitidos ou nulos.

O método de pagamento com QR Code não suporta gorjetas. O parcelamento em QR é tratado pela carteira do portador do cartão. Não envie Installments, PlanId, Interest, OperationMode ou Tip em vendas com QR Code — se enviados, são ignorados.

Antes de começar

Antes de realizar um pagamento com QR Code:

Um Connector deve ser criado e validado com Polling
O Modo POS Integrado deve estar ativo
O terminal deve suportar pagamentos com QR Code

Passo 1: Inicie um pagamento com QR Code

Para iniciar um pagamento com QR Code, chame a operação Sale com o parâmetro SaleType definido como QrCode.

Parâmetros para uma venda com QR Code

Parâmetro	Tipo	Obrigatório	Descrição
`Amount`	Long	Não	Valor da transação na moeda local (por exemplo, `7500` = 75,00). Se omitido, o POS solicita o valor.
`SaleType`	Enum	Não	Defina como `QrCode` (ou enum/inteiro equivalente). Se omitido, o terminal exibe a tela de seleção do tipo de pagamento.
`PrintOnPos`	Bool	Não	Indica se o POS deve imprimir um recibo quando aplicável. O comportamento pode variar conforme o fluxo da carteira.
`EmployeeId`	Int	Não	Identificação opcional do operador.
`SkipReceipt`	Bool	Não	Se `true`, ignora a tela de recibo do cliente quando aplicável.
`CallerId`	String	Não	ID gerado pelo sistema de automação, usado para consultar a transação depois com o Check Status. Sem caracteres especiais ou Unicode.

Como mencionado na visão geral, os parâmetros de parcelamento e gorjeta não são suportados em vendas com QR Code e devem ser omitidos.

Exemplo: requisição de venda com QR Code

O exemplo a seguir mostra como chamar um pagamento com QR Code:

var saleRequest = new SaleRequest
{
    Amount = 7500,                    // 75.00 in local currency
    SaleType = SaleType.QrCode,
    PrintOnPos = true,
    SkipReceipt = false
};

var saleResult = await connector.SaleAsync(saleRequest);

Depois que a requisição é enviada, o POS processa a entrada e exibe o QR Code na tela para o cliente escanear.

Passo 2: Interação com o cliente

O cliente escaneia o QR Code com um aplicativo de pagamento compatível (carteira). Em seguida, o POS aguarda a confirmação do pagamento pela carteira.

O comportamento de timeout e cancelamento é gerenciado pelo POS. A operação pode ser cancelada somente até o cliente escanear o QR Code. Quando o terminal detecta a leitura, o botão de cancelar é desabilitado e a venda não pode mais ser cancelada no terminal. Se o cliente cancelar antes de escanear ou a operação for abortada, o fluxo volta ao modo de espera.

Passo 3: Trate a resposta

Assim que o cliente conclui o pagamento na carteira, o POS retorna uma resposta estruturada. Veja abaixo um exemplo de resposta completa para uma venda com QR Code:

{
  "Code": 0,
  "Message": "APPROVED",
  "AuthorizationCode": "123456",
  "Amount": 7500,
  "OriginalAmount": 7500,
  "AccountingDate": "2025-08-25T16:11:23.0000000Z",
  "RealDate": "2025-08-25T13:11:50.8570000-03:00",
  "SaleType": "QrCode",
  "CommerceCode": "1234567890",
  "TerminalId": "GET00123",
  "CardType": null,
  "CardBrand": null,
  "Last4Digits": null
}

Como mostrado no exemplo, os campos específicos de cartão (como tipo de cartão, bandeira ou últimos 4 dígitos) não se aplicam a transações com QR Code e retornam como null ou vazios.

Quando o cliente conclui uma venda com QR Code por um aplicativo de carteira, alguns atributos da resposta podem retornar como null.

Consultando o status depois: Uma transação QR PCT (Point of Capture) consultada com o Check Status sempre retorna AUTHORIZED (código 1) — nunca APPROVED. Um QR Code processado com dados de cartão retorna APPROVED (código 0) após a captura.

Sempre verifique o parâmetro Code e o SaleType antes de processar o resultado.

Próximos passos

Para pagamentos com cartão e uma visão geral completa dos parâmetros de Sale, consulte o guia Pagamento em Passo Único.
Para processar reembolsos de transações com QR Code, consulte o guia Reembolso.