# Referência de tabelas de códigos

Este documento funciona como repositório central de todos os códigos padronizados usados como variáveis nas requisições do Sistema Host e nas respostas do Pinpad. Esses identificadores são essenciais para interpretar dados, identificar erros e configurar comportamentos de transação.

## Códigos de tipo de transação (TTY)

Definido no campo `[TTY]` durante a inicialização (**Y19**). Ele determina a natureza financeira da operação.

| Código | Valor    | Descrição                                               |
| ------ | -------- | ------------------------------------------------------- |
| **00** | Compra   | Compra padrão de bens ou serviços.                      |
| **01** | Débito   | Transação de débito padrão.                             |
| **02** | Crédito  | Transação de crédito padrão.                            |
| **09** | Cashback | Compra com saque em dinheiro (Compra con Vuelto).       |
| **20** | Estorno  | Reversão ou devolução de fundos (Anulación/Devolución). |

## Códigos de tipo de conta (TDC)

Usado no campo `[TDC]` do comando **Y15** para sugerir um tipo de conta de destino ao kernel EMV.

| Código | Valor            | Descrição                                    |
| ------ | ---------------- | -------------------------------------------- |
| **N**  | Não especificado | Valor padrão que indica nenhuma preferência. |
| **1**  | Conta corrente   | Conta corrente padrão (Cuenta Corriente).    |
| **2**  | Conta poupança   | Conta de poupança padrão (Cuenta de Ahorro). |

## Códigos de erro de comunicação (Y0E)

Retornado pelo Pinpad no campo `[COE]` de uma resposta **Y0E** quando uma transação falha ou é interrompida.

| Código | Mensagem             | Causa / Significado                                                     |
| ------ | -------------------- | ----------------------------------------------------------------------- |
| **01** | **CANCELADO**        | O usuário pressionou o botão vermelho "Cancela" ou o Host enviou `Y06`.  |
| **02** | **FALLA LECTURA**    | Falha na leitura do chip ou da tarja, ou restrição de fallback acionada. |
| **03** | **TARJETA INVÁLIDA** | Aplicação do cartão não suportada ou cartão bloqueado.                  |
| **04** | **ERROR EMV**        | Falha de protocolo durante o fluxo EMV Nível 3.                         |
| **05** | **ERROR PIN**        | A entrada segura falhou ou foi cancelada pelo usuário.                  |
| **06** | **MONTO INVÁLIDO**   | O valor informado está malformado ou excede os parâmetros máximos.      |
| **07** | **TIMEOUT**          | O tempo de espera da ação do usuário ou do comando expirou.             |
| **08** | **SIN LLAVES**       | Injeção DUKPT ausente no slot 3/4 ou chaves RSA ausentes.               |
| **99** | **ERROR GRAL**       | Exceção interna não tratada ou falha geral do sistema.                  |

## Tags EMV comuns (CPG - TLV)

Em uma resposta **Y02**, o campo `[CPG]` contém uma string de dados codificados em Tag-Length-Value (TLV). Essas tags são críticas para montar as mensagens de autorização.

| Tag      | Nome                          | Descrição                                                             |
| -------- | ----------------------------- | --------------------------------------------------------------------- |
| **9F26** | Application Cryptogram        | O criptograma primário (ARQC ou TC) gerado pelo cartão.               |
| **9F10** | Issuer Application Data       | Dados proprietários exigidos pelo emissor para validação.             |
| **9F37** | Unpredictable Number          | Número aleatório gerado pelo terminal para dar unicidade à transação. |
| **95**   | Terminal Verification Results | Resultados das validações offline realizadas pelo terminal.           |
| **9B**   | Transaction Status Info       | Indica as funções executadas durante o fluxo da transação.            |
| **9C**   | Transaction Type              | Código EMV interno (por exemplo, `00` para bens e `09` para cashback). |

> Você precisa de um parser TLV padrão no lado do Sistema Host para extrair esses valores específicos para suas mensagens de autorização ISO 8583.

## Modo de entrada (MDI)

Identifica a interface física de hardware usada para apresentar o cartão.

| Caractere | Modo            | Interface de hardware              |
| --------- | --------------- | ---------------------------------- |
| **C**     | **Chip**        | Slot de contato EMV.               |
| **B**     | **Banda**       | Leitor de tarja magnética (swipe). |
| **L**     | **Contactless** | Antena NFC (tap).                  |
| **M**     | **Manual**      | Cartão digitado manualmente.       |
| **E**     | **Error**       | O cartão não pôde ser lido.        |

## Controle de criptografia do PAN (ENC)

Definido no campo `[ENC]` de `Y19` e `Y02` para controlar a criptografia DUKPT do PAN.

| Código | Comportamento                                                                   |
| ------ | ------------------------------------------------------------------------------- |
| **0**  | Criptografia DUKPT do PAN desativada.                                           |
| **1**  | Criptografia DUKPT do PAN ativada.                                              |
| **2**  | PAN criptografado com o slot 3, com DUKPT ativado (força o modo de chave única). |

## Posição da chave mestra (PMK)

Definido no campo `[PMK]` de `Y19` e `Y02`. Somente o PMK do PIN é informado; o PMK do PAN é sempre o PMK do PIN mais um.

| Valor   | PIN PMK | PAN PMK     |
| ------- | ------- | ----------- |
| **0–9** | O valor | O valor + 1 |
| **N**   | —       | —           |

O valor `N` significa que nenhum PIN é solicitado e nenhum PMK é informado. Nesse caso, o firmware assume o slot 3 para o PIN e o slot 4 para o PAN quando há uma chave presente. A posição padrão da chave mestra (POSMK) é `3`.

## Números de série de chave (KSN)

O DUKPT retorna um Key Serial Number junto de cada elemento criptografado.

| Campo     | Comprimento           | Descrição                           |
| --------- | --------------------- | ----------------------------------- |
| `KSN-PAN` | 20 dígitos (10 bytes) | KSN do PAN criptografado com DUKPT. |
| `KSN`     | 20 dígitos (10 bytes) | KSN do PIN DUKPT.                   |

> Os slots de chave, os contadores independentes e o mascaramento do PAN são explicados em [Criptografia do Pinpad](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-pinpad-encryption).