Getnet DocsGetnet Docs

Arquitetura e Fluxo de Dados 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

Este documento fornece uma visão técnica da arquitetura Cartão Presente dentro do Single Entry Point (SEP). Ele explora como os terminais físicos se integram à Regional API para processar transações seguras em toda a América Latina.

Arquitetura de Alto Nível

A solução SEP Cartão Presente utiliza a mesma infraestrutura do e-commerce (Regional API), mas substitui os dados do cartão inseridos pelo cliente por payloads protegidos por hardware.

Topologias de Conectividade

TopologiaCaminho do Fluxo de DadosCaso de Uso
Integração DiretaTerminal → Getnet CloudPOS/mPOS independente onde o firmware do dispositivo é o cliente da API.
Merchant HostTerminal → Backend do Estabelecimento → Getnet CloudSistemas de varejo integrados onde um servidor central gerencia a lógica de negócio e a orquestração da API.

Os Quatro Pilares Técnicos

A arquitetura baseia-se em quatro componentes fundamentais para garantir a segurança e a conformidade regional:

  1. Identidade do Terminal: O terminal_number exclusivo (ancorado no objeto terminal) identifica a origem física.
  2. Modos de Entrada Seguros: O entry_mode (chip, chip_contactless, magnetic_stripe) dita o payload necessário.
  3. Payloads de Hardware: Strings criptografadas EMV TLV (para chips) ou Track 2 (para tarja) geradas dentro do enclave seguro do hardware.
  4. Segurança do PIN (DUKPT): Quando o online_pin é usado, o esquema DUKPT garante que o pin_block e o ksn (Key Serial Number) sejam transmitidos com segurança.

Fluxos de Transação

Fluxo de Passo Único (Venda)

Fluxo padrão onde a autorização e a captura ocorrem em uma única chamada de API usando DIRECT_CREDIT ou DIRECT_DEBIT.

sequenceDiagram participant Card as Physical Card participant Terminal as Hardware Terminal participant App as Client Application participant API as Getnet Regional API participant Issuer as Card Issuer Card->>Terminal: Insert/Tap/Swipe Terminal->>Terminal: Encrypt Data (EMV/Track 2/PIN) Terminal->>App: Return Secure Payload App->>API: POST /v2/payments (Single-Step) API->>API: Validate Terminal & Decrypt PIN API->>Issuer: Request Authorization Issuer-->>API: Approved API-->>App: Return payment_id (Status: APPROVED) App->>Terminal: Display Result & Print Receipt

Fluxo de Dois Passos (Pré-autorização e Captura)

Usado para aluguéis ou hospitalidade, onde o valor final é confirmado posteriormente.

sequenceDiagram participant App as Client Application participant API as Getnet Regional API participant Issuer as Card Issuer Note over App, Issuer: Passo 1: Autorização (Cartão Presente) App->>API: POST /v2/payments (DIRECT_CREDIT_AUTHORIZATION) API->>Issuer: Hold Funds Issuer-->>API: Authorized API-->>App: Status: AUTHORIZED (payment_id) Note over App, Issuer: Passo 2: Captura (Card Not Present) App->>API: POST /v2/payments/capture API->>Issuer: Settle Funds Issuer-->>API: Confirmed API-->>App: Status: CAPTURED

Pagamento via QR Code (Visa/Mastercard)

Este fluxo está disponível para pagamentos via QR Code Visa e Mastercard em terminais físicos.

sequenceDiagram participant App as Client Application participant API as Getnet Regional API participant Wallet as Customer Wallet App->>API: POST /v2/payments/qrcode (serial_number, amount) API-->>App: 201 Created (qr_code payload) App->>App: Render QR on Terminal Screen Wallet->>API: Scans & Authorizes API-->>App: PAYMENT_APPROVED (Webhook or Status Check)

Variações Regionais

A arquitetura se adapta aos requisitos regionais específicos definidos na API:

  • Argentina e Chile: Apresentam um endpoint dinâmico de Cotações de Parcelamento (/v2/payments/quotes) para buscar planos com base no BIN do cartão.
  • México: Utiliza planos de parcelamento pré-definidos diretamente na requisição de pagamento.

Segurança e Conformidade

  • Liability Shift: Ao utilizar a tecnologia EMV (Chip & PIN), a responsabilidade por fraude passa do estabelecimento para o emissor.
  • Redução do Escopo PCI-DSS: A criptografia de hardware (P2PE/DUKPT) garante que os ambientes dos estabelecimentos comerciais nunca manipulem dados de cartão em texto aberto.
  • End-to-End Encryption: Os dados do cartão são criptografados no ponto de interação (POI) e decifrados apenas dentro dos Módulos de Segurança de Hardware (HSM) seguros da Getnet.

Veja Também