Getnet DocsGetnet Docs

Introdução ao Cartão Presente

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Uma transação Cartão Presente ocorre quando um pagamento é iniciado por meio de um hardware físico—como um terminal POS, mPOS ou um PIN pad integrado—onde o cartão é lido fisicamente pelo dispositivo.

Diferentemente do e-commerce (Card-Not-Present), onde o usuário digita manualmente os dados do cartão em um navegador, as transações dependem da troca de dados criptografados gerados pelo hardware. No contexto da Regional API, isso significa afastar-se de números de cartão em texto aberto e adotar payloads seguros de EMV (Chip) e Tarja Magnética que utilizam criptografia DUKPT (Derived Unique Key Per Transaction).

Os Quatro Pilares do Cartão Presente

Para entender como o Single Entry Point (SEP) lida com vendas físicas, você deve dominar estes quatro conceitos fundamentais:

1. Identidade do Terminal

Cada transação física deve ser vinculada a uma peça de hardware específica registrada no ecossistema Getnet. Isso é gerenciado pelo objeto terminal, que exige um terminal_number exclusivo. Esse ID informa ao gateway exatamente qual dispositivo físico está solicitando a autorização, o que é crítico para a segurança, relatórios fiscais regionais e conciliação específica do terminal.

2. Modos de Entrada Seguros

O campo entry_mode identifica como os dados do cartão foram capturados, o que determina os requisitos de dados subsequentes no objeto card:

  • chip: O cartão foi inserido em um leitor de Integrated Circuit Card (ICC).
  • magnetic_stripe: O cartão foi passado pelo leitor de tarja, exigindo os dados completos do track_2.
  • chip_contactless: O cartão ou carteira móvel foi aproximado via Near Field Communication (NFC).

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

A verificação não é mais apenas uma “checagem de CVV”. Nos fluxos de Cartão Presente, o cardholder_verification_method define o aperto de mão (handshake) de segurança:

  • online_pin: Exige o pin_block criptografado e o ksn (Key Serial Number) do hardware.
  • no_cvm: Usado para transações de baixo valor ou por aproximação onde o PIN não é exigido.

4. O Payload Criptografado

Em vez de enviar dados sensíveis do cartão em texto aberto, seu leitor de hardware gera strings seguras:

  • emv: Uma coleção de tags Tag-Length-Value (TLV) capturadas do chip.
  • track_2: O equivalente digital da tarja magnética, muitas vezes exigido mesmo em transações com chip por questões de compatibilidade.

Topologias de Rede: Como os Dados Chegam à API

A Regional API suporta duas formas principais para a comunicação do seu hardware:

  • Integração Direta: O terminal conecta-se diretamente aos endpoints de nuvem da Getnet.
  • Merchant Host: O terminal envia os dados para o seu servidor interno (Host), que então encaminha a requisição para a Regional API.

Por que Cartão Presente?

O principal motivador para a integração de hardware é o Liability Shift. Quando você processa uma transação usando tecnologia EMV (Chip & PIN), a responsabilidade por transações fraudulentas passa do estabelecimento comercial para o emissor do cartão. Como o chip físico e o PIN criptografado são quase impossíveis de clonar, o gateway trata essas transações com o mais alto nível de confiança.