Requisitos do Terminal para Cartão Presente

Este documento de referência descreve os requisitos técnicos para integrar um terminal de hardware físico à Getnet Regional API para transações Cartão Presente. Antes de enviar qualquer requisição de pagamento, seu terminal deve atender a essas especificações para garantir o sucesso da autorização e a conformidade.

Visão Geral

Cada transação Cartão Presente na Regional API está vinculada a um dispositivo físico específico e registrado. O gateway utiliza a identidade do terminal para aplicar políticas de segurança, regras fiscais regionais e permitir a conciliação por dispositivo. Uma requisição que não apresente ou possua uma configuração de terminal inválida será rejeitada.

Requisitos de Requisição da API

Cabeçalho Obrigatório

Todas as requisições de pagamento Cartão Presente devem incluir o seguinte cabeçalho HTTP:

Cabeçalho	Valor	Descrição
`x-transaction-channel-entry`	`XX`	Identifica a plataforma que está enviando a transação. Este código é atribuído pela Getnet e deve ser solicitado à equipe de Suporte à Integração.

Este cabeçalho é obrigatório para todas as transações integradas por hardware.

Objeto `terminal` Obrigatório

O objeto terminal deve ser incluído dentro de data.payment em todas as requisições Cartão Presente. Ele identifica o dispositivo físico registrado que está processando a transação.

"data": {
  "payment": {
    "terminal": {
      "terminal_number": "21000334"
    }
  }
}

Campo	Tipo	Obrigatório	Descrição
`terminal_number`	`string`	Sim	O identificador exclusivo do terminal físico registrado. Fornecido pela Getnet durante o onboarding do dispositivo.

O objeto terminal é um objeto obrigatório para Cartão Presente, conforme definido no esquema da API. Uma requisição sem um terminal_number válido será rejeitada.

Capacidades de Hardware

Seu terminal físico deve suportar as seguintes capacidades para processar transações Cartão Presente por meio da Regional API:

Modos de Entrada de Cartão

O terminal deve ser capaz de ler pelo menos um dos seguintes modos de entrada, que determina o payload de dados enviado à API:

Modo de Entrada (`entry_mode`)	Requisito de Hardware	Principal Campo de Dados
`chip`	Leitor de slot ICC (Integrated Circuit Card)	`emv` (string TLV)
`chip_contactless`	Leitor NFC (Near Field Communication)	`emv` (string TLV)
`magnetic_stripe`	Leitor de cabeça de tarja magnética	`track_2`

Métodos de Verificação do Portador (CVM)

O terminal deve suportar pelo menos um dos seguintes métodos de verificação, que determina os campos de segurança adicionais exigidos na requisição:

CVM (`cardholder_verification_method`)	Requisito de Hardware	Campos Adicionais Exigidos
`online_pin`	PIN pad seguro com criptografia DUKPT	`pin_block`, `ksn`
`offline_pin`	Verificação local do chip ICC	Nenhum (lidado pelo cartão)
`signature`	Tela ou comprovante de papel	Nenhum (estabelecimento armazena a assinatura)
`no_cvm`	Nenhum (aproximação de baixo valor)	Nenhum

Processamento de Chip EMV

Para os modos de entrada chip e chip_contactless, o terminal deve:

Ler e analisar os dados TLV do Circuito Integrado (IC) do cartão.
Gerar um Application Cryptogram (ARQC) para cada transação.
Concatenar todas as EMV Tags em uma única string codificada em hex para o campo emv.
Fornecer o Application Identifier (AID) no campo aid.

Criptografia de PIN (DUKPT)

Para transações com online_pin, o PIN pad do terminal deve:

Criptografar o PIN usando o esquema de gerenciamento DUKPT (Derived Unique Key Per Transaction).
Gerar um PIN Block no formato ISO 9564-1 Format 0 (ISO-0).
Fornecer o KSN (Key Serial Number) — uma string hexadecimal de 20 dígitos — para permitir que o HSM da Getnet derive a chave de decifração correta.

Campo	Formato	Exemplo
`pin_block`	String codificada em hex	`A0B6BA8D53C8D3C3`
`ksn`	String hex de 20 dígitos	`BC756011020000400001`

Requisitos de Conectividade

Seu terminal deve ser capaz de alcançar os endpoints da Getnet Regional API via HTTPS. As seguintes URLs base se aplicam:

Ambiente	URL Base
Sandbox	`https://api-sbx.pre.globalgetnet.com`
Produção	`https://api.pre.globalgetnet.com`

Topologias de Rede

A Regional API suporta duas topologias principais de integração:

Topologia	Descrição
Integração Direta	O firmware do terminal atua como o cliente da API, lidando com a autenticação OAuth 2.0 e a construção do JSON diretamente.
Merchant Host	O terminal captura os dados do hardware (EMV, Track 2, PIN Block) e os encaminha para um servidor de backend do estabelecimento comercial, que então constrói e envia a requisição da API.

Registro do Terminal

Antes de processar transações reais, seu terminal deve estar registrado na Getnet. Entre em contato com a equipe de Suporte à Integração para:

Obter um terminal_number válido para cada dispositivo físico.
Solicitar o código x-transaction-channel-entry para sua plataforma de integração.
Configurar a injeção de chaves DUKPT para terminais habilitados para PIN.

Resumo de Campos Obrigatórios

A tabela a seguir consolida todos os campos obrigatórios para uma requisição de pagamento Cartão Presente:

Campo / Cabeçalho	Localização	Obrigatório Para
`x-transaction-channel-entry: XX`	Cabeçalho HTTP	Todas as transações
`data.payment.terminal.terminal_number`	Corpo da Requisição	Todas as transações
`data.payment.card.entry_mode`	Corpo da Requisição	Todas as transações
`data.payment.card.emv`	Corpo da Requisição	`chip`, `chip_contactless`
`data.payment.card.aid`	Corpo da Requisição	`chip`, `chip_contactless`
`data.payment.card.track_2`	Corpo da Requisição	`magnetic_stripe` (e muitas vezes `chip`)
`data.payment.card.pin_block`	Corpo da Requisição	CVM `online_pin`
`data.payment.card.ksn`	Corpo da Requisição	CVM `online_pin`
`data.payment.card.seq_number`	Corpo da Requisição	`chip` com `online_pin`