Processar pagamentos com QR Code

Este guia explica como usar a tela do terminal para exibir QR Codes dinâmicos em fluxos de pagamento com carteira digital usando o comando Y0Q.

Como funciona

Nos pagamentos com cartão, o terminal lê os dados de um meio físico. A transação QR inverte esse fluxo: o terminal exibe os dados de pagamento (a string do QR Code) e o dispositivo móvel do usuário faz a leitura.

• Desvio do EMV: O fluxo QR não usa a sequência de inicialização padrão Y19/Y15, porque ignora completamente o kernel EMV.
• Renderização dinâmica: O terminal recebe uma string alfanumérica bruta do Sistema Host e renderiza a matriz QR 2D no visor.
• Exibição do valor: Se a string de dados do QR contiver a Tag 54 (Amount), o Pinpad adiciona automaticamente o símbolo ”$” e exibe o valor na tela.

Todo o fluxo é gerenciado pelo comando Y0Q. Enquanto o QR é exibido, o Pinpad bloqueia outras tentativas de transação e ignora qualquer comando diferente do cancelamento Y06.

Passo 1: Renderize o QR Code (requisição Y0Q)

O Sistema Host reúne os dados de destino do pagamento (ex: uma string de carteira) e os envia diretamente ao Pinpad.

Tabela TDP (tipos de tela)

O campo TDP permite que o Sistema Host navegue entre três estados de UI específicos:

Passo 2: Valide a exibição (resposta Y0Q)

O Pinpad retorna um ACK imediatamente após validar e analisar o comando. Em seguida, a camada de UI gera a matriz QR e a exibe na tela.

Passo 3: Trate as mudanças de status (opcional)

Se o Sistema Host precisar informar o progresso (ex: “Processando informações”), ele deve primeiro enviar um comando Y06 para interromper a exposição do QR. Depois, ele envia um novo comando Y0Q com TDP definido como “02”.

Finalize ou cancele

A transação financeira ocorre entre o dispositivo do usuário e o provedor da carteira. Por isso, o Pinpad não sabe automaticamente quando o pagamento foi concluído. O Sistema Host deve monitorar o status na própria autorizadora.

• Conclusão pelo Host: Após a confirmação do pagamento, o Sistema Host deve enviar um comando Y06 ou um comando Y0Q com TDP definido como “03” para limpar a tela e retornar ao estado IDLE.
• Cancelamento automático: Se o usuário cancelar a ação no dispositivo ou o tempo limite for atingido, o Pinpad retorna uma resposta Y0Q com um código de status ([STS]):
• “0”: Cancelado pelo usuário.
• “1”: Cancelado por timeout.

Referência de implementação (Kotlin)

A lógica a seguir define como o comando Y0Q é processado e renderizado no aplicativo.

Tratamento e análise do comando

A classe CommandY0Q faz a análise dos campos recebidos, enquanto handleCommandY0Q aciona a lógica de exibição na UI.

/**
 * This class represents a Y0Q command with functionality to parse 
 * and manage the received command fields. It extracts the content 
 * to be displayed in the QR (QRD).
 */
class CommandY0Q(rawCmd: String?) : Command()

/**
 * Handles the Y0Q command, "Display QR".
 * This method parses and displays a QR on the terminal screen.
 */
private fun handleCommandY0Q(inCmd: String?)

Geração da matriz QR

O Pinpad usa a biblioteca ZXing para codificar a string alfanumérica em um bitmap de matriz 2D.

/**
 * Generate QR codes using the ZXing library.
 * Uses `BarcodeEncoder` to encode content into a QR code bitmap.
 */
object QrGeneration { ... }

Exemplo de comunicação

Este exemplo ilustra o fluxo de exibição de um QR Code com valor de $200.30 e o cancelamento manual posterior pelo Host.

O bloco de código a seguir mostra a solicitação de exibição do QR pelo Host (Tag 54 = 200.3):

[SP] <STX>Y0Q<FS>010<FS>00020101021230230019ar.com.globalgetnet...5405200.3...<FS><ETX>a

O Pinpad valida e exibe:

[PP] <ACK>

Caso o host aborte a exposição do QR:

[SP] <STX>Y06060<ETX>j

Nesse caso, o Pinpad confirma o cancelamento:

[PP] <ACK>

Próximos passos

Com os pagamentos por QR Code implementados, você pode concluir sua integração revisando:

1. Cancelamentos e Estornos: Saiba como o comando Y06 interage com sessões QR ativas.
2. Comandos da API: Consulte a referência técnica completa de cada campo do payload Y0Q.