Validação de PIN

No ecossistema Cartão Presente, o Número de Identificação Pessoal (PIN) serve como o Método de Verificação do Portador (CVM) mais seguro. Diferente do CVV estático usado no e-commerce, uma interação de PIN envolve um aperto de mão (handshake) criptográfico sofisticado entre o terminal de hardware, o chip do cartão e o sistema de autorização do emissor para garantir que dados sensíveis nunca sejam transmitidos em “texto aberto”.

Validação de PIN Online vs. Offline

A Regional API suporta dois métodos distintos para validar o PIN de um cliente, determinados pela configuração do cartão e pelas capacidades do terminal.

Validação de PIN Offline

O PIN é validado localmente pelo chip seguro no próprio cartão.

Processo: O cliente insere seu PIN no terminal, e o terminal o envia diretamente para o Circuito Integrado (IC) do cartão para comparação.
Benefício: Permite a verificação mesmo se o terminal estiver temporariamente offline ou em um ambiente de baixa conectividade.
Impacto na API: Na sua requisição, cardholder_verification_method é definido como offline_pin e, como a verificação ocorreu localmente, o pin_block normalmente não é enviado ao gateway.

Validação de PIN Online

O PIN é criptografado pelo hardware e enviado ao emissor do cartão para verificação em tempo real.

Processo: O terminal criptografa o PIN usando uma chave de transação exclusiva e o empacota em um PIN Block.
Segurança: Utiliza DUKPT (Derived Unique Key Per Transaction) para garantir que, mesmo se a chave de uma transação for comprometida, todas as outras transações permaneçam seguras.
Impacto na API: Este método exige a transmissão tanto do pin_block quanto do ksn (Key Serial Number) no payload da API.

Os Componentes do PIN Online Seguro

Ao implementar o PIN Online, sua integração de hardware deve fornecer três elementos criptográficos críticos para a Regional API:

PIN Block

Uma estrutura de dados segura e criptografada (normalmente 8 bytes para TDES ou 16 bytes for AES) que transporta o PIN. A maioria das implementações utiliza o ISO 9564-1 Format 0 (ISO-0), que realiza um XOR do PIN do cliente com os últimos 12 dígitos do número do cartão (PAN) para garantir que o bloco resultante seja exclusivo para aquele cartão específico.

KSN (Key Serial Number)

Um identificador hexadecimal de 20 dígitos que atua como o “mapa” para o gateway decifrar o PIN. Ele é composto por um ID de chave base, um identificador de dispositivo e um contador de transações.

Função: O KSN permite que o HSM (Hardware Security Module) da Getnet derive a Working Key exata usada pelo terminal para aquela transação específica.

Criptografia DUKPT

O esquema de gerenciamento Derived Unique Key Per Transaction (DUKPT) garante que o terminal gere uma nova chave de criptografia, não reutilizável, para cada leitura de cartão. Isso evita “ataques de repetição” (replay attacks) e garante a segurança de ponta a ponta, desde o PIN pad físico até o gateway da Getnet.

Mapeamento Técnico na Regional API

Para qualquer transação onde cardholder_verification_method for definido como online_pin, os seguintes campos no objeto card são obrigatórios:

"card": {
  "entry_mode": "chip",
  "cardholder_verification_method": "online_pin",
  "pin_block": "A0B6BA8D53C8D3C3",
  "ksn": "BC756011020000400001",
  "emv": "9f2701809f3303e0f8c8950580000080..."
}

Campo	Requisito	Descrição
`cardholder_verification_method`	Obrigatório	Definido como `online_pin`.
`pin_block`	Obrigatório	Os dados do PIN criptografados em hexadecimal.
`ksn`	Obrigatório	O número de série da chave de 20 dígitos em hexadecimal.