# Especificações de EMV Tags para Cartão Presente

Em um ambiente **Cartão Presente**, a segurança da transação é ancorada na troca de dados **Tag Length Value (TLV)** entre o chip do cartão e o gateway da Getnet. Esta página fornece uma referência técnica para as EMV Tags específicas normalmente incluídas no payload `emv` da **Regional API**.

## A Anatomia de uma Tag (TLV)

Cada elemento de dado dentro da string `emv` gerada pelo hardware segue o formato padrão TLV:

- **Tag:** Um identificador hexadecimal de 1 ou 2 bytes (ex: `9F26`).
- **Length:** O tamanho do valor subsequente em bytes.
- **Value:** O payload de dados real (um criptograma ou código de moeda).

## EMV Tags Principais (Obrigatórias e Comuns)

Com base em payloads de hardware validados (como a integração Chile/CLP), as seguintes tags são críticas para uma autorização bem-sucedida.

| Tag | Nome | Origem | Descrição |
| --- | --- | --- | --- |
| **9F26** | **Application Cryptogram (ARQC)** | ICC | Um criptograma exclusivo de 8 bytes gerado pelo chip do cartão e usado pelo emissor para verificar a autenticidade do cartão em cada transação. |
| **9F02** | **Amount, Authorized** | Terminal | O valor da transação em formato numérico (em centavos). |
| **9F34** | **CVM Results** | Terminal | Registra o resultado da negociação do Método de Verificação do Portador (PIN Online verificado, Sem CVM). Usado pelo gateway para confirmar o método de verificação aplicado. |
| **95** | **Terminal Verification Results (TVR)** | Terminal | Um bitmap de 5 bytes indicando quais verificações de segurança foram realizadas e seus resultados (autenticação de dados offline, verificação de PIN). |
| **9F33** | **Terminal Capabilities** | Terminal | Define as capacidades suportadas pelo terminal para entrada de dados do cartão, CVM e recursos de segurança. |
| **9F10** | **Issuer Application Data (IAD)** | ICC | Dados proprietários do emissor incorporados no cartão, usados para gerenciamento de risco e validação de criptograma. |
| **9F36** | **Application Transaction Counter (ATC)** | ICC | Um contador mantido pelo chip do cartão que incrementa a cada transação, evitando ataques de repetição. |
| **9F37** | **Unpredictable Number** | Terminal | Um número aleatório de 4 bytes gerado pelo terminal para cada transação para garantir a exclusividade do criptograma. |
| **5F2A** | **Transaction Currency Code** | Terminal | O código numérico da moeda ISO 4217 (`0032` para CLP, `0986` para BRL). |
| **5F34** | **PAN Sequence Number (PSN)** | ICC | Diferencia entre múltiplos cartões emitidos para a mesma conta que compartilham o mesmo Primary Account Number (PAN). |
| **9A** | **Transaction Date** | Terminal | A data em que a transação foi iniciada, no formato AAMMDD. |
| **9C** | **Transaction Type** | Terminal | Indica o tipo de transação financeira (`00` para Compra). |
| **9F1A** | **Terminal Country Code** | Terminal | O código numérico do país ISO 3166-1 da localização do terminal (`0152` para o Chile). |

## Validação Detalhada do Payload

Para garantir que sua implementação seja robusta, seu hardware deve concatenar essas tags em uma única string hexadecimal para o campo `data.payment.card.emv`.

<Callout type="warning">

O campo `emv` deve conter todas as tags como uma única string codificada em hex sem espaços. Não inclua espaços ou separadores entre os elementos TLV.

</Callout>

### Exemplo de String Decodificada

Aqui está um detalhamento de como o gateway lê um payload de chip validado extraído de uma transação real:

> **`9F26 08 819BA36F3F793414`**
> - **Tag:** `9F26` (Application Cryptogram)
> - **Length:** `08` (8 bytes)
> - **Value:** `819BA36F3F793414` (O ARQC)

A string `emv` completa na requisição da API ficaria assim (todas as tags concatenadas sem espaços):

```
9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e0300
```

## Melhores Práticas de Segurança

- **Não utilize listas de tags fixas (hardcoded):** Os requisitos de tags podem evoluir com base em regulamentações regionais ou atualizações das bandeiras de cartão. Seu parser deve ser flexível o suficiente para lidar com tags inesperadas sem falhar.
- **Codificação Hexadecimal:** Certifique-se de que todos os dados TLV sejam convertidos corretamente para uma string codificada em hexadecimal antes do envio para a API.
- **Tratamento de Dados Sensíveis:** Embora tags como `5A` (PAN) ou `57` (Track 2 Equivalent Data) existam no padrão EMV, elas são normalmente enviadas em campos dedicados da API (`card.number`, `card.track_2`) em vez de dentro da string genérica `emv` para manter a conformidade PCI DSS.
- **Validação de ARQC:** O Application Cryptogram (`9F26`) é a tag mais crítica. Um ARQC inválido ou ausente resultará em uma transação recusada.

## Leia Mais

- **Validação de PIN**: Requisitos técnicos para transmissão de `pin_block` e `ksn`.
- **Modos de Entrada do Cartão**: Como alternar entre `chip`, `chip_contactless` e `magnetic_stripe`.
- **Visão Geral da Tecnologia EMV**: Aprofundamento em tags TLV e criptogramas de chip.
- **Pagamentos de Passo Único**: Guia passo a passo para sua primeira venda física.