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.

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.

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.