# 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.

| Campo | Atributo | Descrição |
| --- | --- | --- |
| **[CID]** | 3 ANS | Identificador do Comando: **“Y0Q”**. |
| **[TDP]** | 2 N | **Tipo de Tela**: Define qual estado da UI exibir. |
| **[TO]** | 3 N | **Timeout**: Tempo de exposição do QR em segundos (ex: "060"). |
| **[QRD]** | 1..512 ANS | **Dados do QR**: A string alfanumérica a ser codificada na matriz. |

#### Tabela TDP (tipos de tela)

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

| Valor | Descrição |
| --- | --- |
| **"01"** | **Exibir QR**: Renderiza a imagem do QR e o valor opcional. |
| **"02"** | **Processando**: Exibe "Procesando información". |
| **"03"** | **Idle**: Retorna o terminal ao seu estado base de espera. |

## 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.

```kotlin
/**
 * 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()

```

```kotlin
/**
 * 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.

```kotlin
/**
 * 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):

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

```

O Pinpad valida e exibe:

```text
[PP] <ACK>

```

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

```text
[SP] <STX>Y06060<ETX>j

```

Nesse caso, o Pinpad confirma o cancelamento:

```text
[PP] <ACK>

```

## Próximos passos

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

1. [**Cancelamentos e Estornos**](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-cancellations-and-refunds&section=kei2fli2gqggbwgaddtl3xb7): Saiba como o comando `Y06` interage com sessões QR ativas.
2. [**Comandos da API**](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-api-commands&section=g7b851vgbt737kwul1fmgve2): Consulte a referência técnica completa de cada campo do payload `Y0Q`.