Getnet DocsGetnet Docs

Card Present Payment Workflows

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

In a Card Present (CP) environment, the payment workflow is a synchronized interaction between the customer’s physical card, the hardware terminal, and the Getnet Regional API. The integration distinguishes between Authorization (logic) and Capture (financial settlement) to ensure a robust transaction lifecycle.

Based on the validated payloads and API specifications, there are two primary architectural workflows: Single-Step and Two-Step.

Single-Step Workflow (Direct Sale)

The Single-Step workflow is the standard implementation for retail point of sale environments. It authorizes and captures the transaction in one synchronous operation.

sequenceDiagram participant Customer participant Terminal as Hardware Terminal participant POS as POS Application participant API as Getnet API participant Issuer Customer->>Terminal: Inserts Card & Enters PIN Terminal->>POS: Returns Encrypted Payload (EMV, PIN Block) POS->>API: POST /v2/payments (DIRECT_CREDIT) API->>Issuer: Authorize & Capture Issuer-->>API: Approved API-->>POS: Returns payment_id (Status: APPROVED) POS->>Terminal: Display "Approved"

The Technical Process

  1. Card Interaction: The terminal captures the chip (EMV) or magnetic stripe data.
  2. API Request: The system submits a POST /v2/payments with the payment_method set to DIRECT_CREDIT or DIRECT_DEBIT.
  3. Real-time Validation: The gateway validates the hardware secured payloads, including the emv string or track_2 data and, if applicable, the pin_block and ksn.
  4. Instant Settlement: Upon approval from the card issuer, the funds are immediately marked for settlement.

Two-Step Workflow (Pre-Authorization & Capture)

The Two-Step workflow separates the authorization (hold) from the final financial capture.

sequenceDiagram participant POS as POS Application participant API as Getnet API participant Issuer Note over POS, API: Step 1: Authorization POS->>API: POST /v2/payments (DIRECT_CREDIT_AUTHORIZATION) API->>Issuer: Reserve Funds (Hold) Issuer-->>API: Approved API-->>POS: Returns payment_id (Status: AUTHORIZED) Note over POS, API: Step 2: Capture (Later) POS->>API: POST /v2/payments/capture (payment_id) Note right of POS: Requires new unique idempotency_key API->>Issuer: Settle Funds Issuer-->>API: Confirmed API-->>POS: Returns Status: CAPTURED

Step A: Pre-Authorization

  • Method: Submit POST /v2/payments with payment_method set to DIRECT_CREDIT_AUTHORIZATION.
  • Result: The issuer places a temporary “hold” on the customer’s funds. You receive a payment_id with a status of AUTHORIZED.
  • Requirement: This step requires the physical presence of the card to generate the emv or track_2 payload.

Step B: Capture (Settlement)

  • Method: Submit POST /v2/payments/capture using the previously generated payment_id.
  • Logic: This step can be executed via the API without the physical card being present.
  • Amount: You may capture the full authorized amount or a partial amount.
  • Idempotency: Ensure you use a new, unique idempotency_key for the capture request.

Technical Validation for Workflows

All Card Present workflows must adhere to these technical constraints to ensure successful processing:

  • Idempotency Control: Every authorization request must include a unique idempotency_key to prevent duplicate charges during network disruptions.
  • Channel Identification: The header x-transaction-channel-entry: XX is mandatory to signal the gateway that the request originates from a hardware device.
  • Encrypted Verification: If the terminal determines the card requires a PIN, the online_pin verification method must be used, providing the pin_block and ksn during the initial authorization request.

Read More

  • Single-Step Payments Guide: Implementation for immediate sales.
  • Pre-authorized Payments Guide: Managing holds and captures.
  • PIN Validation: Security requirements for PIN based workflows.