Getnet DocsGetnet Docs

Card Present Architecture and Data Flow

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

This document provides a technical overview of the Card Present (CP) architecture within the Single Entry Point (SEP). It explores how physical terminals integrate with the Regional API to process secure transactions across Latin America.

High-Level Architecture

The SEP Card Present solution leverages the same infrastructure as e-commerce (Regional API) but replaces customer-entered card data with hardware-secured payloads.

Connectivity Topologies

TopologyData Flow PathUse Case
Direct IntegrationTerminal → Getnet CloudStandalone POS/mPOS where the device firmware is the API client.
Merchant HostTerminal → Merchant Backend → Getnet CloudIntegrated retail systems where a central server manages business logic and API orchestration.

The Four Technical Pillars

The architecture relies on four fundamental components to ensure security and regional compliance:

  1. Terminal Identity: The terminal_number, logical_code, and serial_number (anchored in the terminal object) identify the physical source.
  2. Secure Entry Modes: The entry_mode (chip, chip_contactless, magnetic_stripe) dictates the required payload.
  3. Hardware Payloads: Encrypted EMV TLV strings (for chips) or Track 2 (for swipe) generated inside the hardware secure enclave.
  4. PIN Security (DUKPT): When online_pin is used, the DUKPT scheme ensures the pin_block and ksn (Key Serial Number) are transmitted securely.

Transaction Flows

Single-Step Flow (Sale)

Standard flow where authorization and capture occur in a single API call using DIRECT_CREDIT or DIRECT_DEBIT.

single step flow

Two-Step Flow (Pre-Authorization & Capture)

Used for rentals or hospitality where the final amount is confirmed later.

two step flow

QR Code Payment (Visa/Mastercard)

This flow is available for Visa and Mastercard QR payments on physical terminals.

Pix Payment (QR / NFC)

This flow generates a Pix QR Code at the terminal for Brazil (BRL) and confirms the payment asynchronously. The terminal displays the QR Code as a scannable image or presents it over NFC (contactless Pix).

  1. The terminal sends a POST request to the /qrcode/pix endpoint with the amount, currency, and customer identifier.
  2. The API returns 201 Created with the qr_code and qr_code_nfc payloads (plus aids) and a WAITING status.
  3. The terminal renders qr_code as a scannable image or presents qr_code_nfc over NFC.
  4. The customer authorizes the payment from their banking app.
  5. Getnet confirms the payment asynchronously through the PIX_UPDATED_TRANSACTIONS webhook.

For the full request and response, see Create a Card Present Pix Payment.

Regional Variations

The architecture adapts to specific regional requirements defined in the API:

  • Argentina & Chile: Feature a dynamic Installment Quotes endpoint (/v2/payments/quotes) to fetch plans based on the card’s BIN.
  • Mexico: Use pre-defined installment plans directly in the payment request.
  • Brazil: Supports terminal-initiated Pix (QR / NFC) payments via the /qrcode/pix endpoint, where the customer authorizes the payment from their banking app.

Security & Compliance

  • Liability Shift: By using EMV technology (Chip & PIN), the responsibility for fraud shifts from the merchant to the issuer.
  • PCI-DSS Scope Reduction: Hardware encryption (P2PE/DUKPT) ensures the merchant environments never handle clear-text card data.
  • End-to-End Encryption: Card data is encrypted at the point of interaction (POI) and only decrypted inside Getnet’s secure Hardware Security Modules (HSM).

See Also