Card In, Card Out - Offline Tokenization

Table of Contents

1. Overview
2. Prerequisites
3. How Offline Tokenization Works
4. Card In, Card Out Process
   1. Stage 1 — Card In
   2. Stage 2 — Card Out (Contact Card)
   3. Stage 2 — Card Out (Contactless Card)
5. Supported Devices
6. HMAC Key Requirements

Overview

This article describes how to implement Card In, Card Out functionality using the offline tokenization feature of Payment Device SDK for Windows & Linux. Offline tokenization allows a customer's payment card to act as a unique identifier across multiple entry and exit points — for example, replacing a physical ticket at a car park or transit gate.

Because a given PAN will always produce the same HMAC token on any device sharing the same injected key, the token can reliably identify the same card without storing or transmitting the actual PAN.

Unlike online tokens, which are returned within the TransactionFinishedEvent, offline tokens are returned within the CardDetailsEvent. The offline token can be used to achieve "card in, card out" functionality — for example, at parking sites where a customer's payment card is used instead of issuing a physical ticket. A given PAN will generate the same token across any devices within the supported devices list of this article, so long as the device is injected with NMI's HMAC key.

Prerequisites

Payment Device SDK

• Requires Payment Device SDK Windows/Linux V1.9+

TMS

• 'Pause Transaction' is required. This functionality is enabled via TMS. 

Device

• NMI has an HMAC Key which our customers use. You will need to ensure your device(s) have this HMAC Key injected by the device distributor or device manufacturer. See HMAC Key Requirements below for device-specific instructions.

How Offline Tokenization Works

Each time a card is presented to a terminal (tap, swipe, or insert), Payment Device SDK generates a PaymentDevice HMAC Token: a 64-byte secure hash of the card's PAN, produced using a cryptographic key stored on the device. An example token looks like:

7F74358FC7CAD013168BB62063B077A294ABBA1AB18DDFF4EBB5287029B56D56

The HMAC token is returned as an XML element within the CARD_HASH_COLLECTION parameter key, which is present in both the CardDetailsEvent and the TransactionFinishedEvent. It is generated for the following transaction types:

• Sale
• Standalone Refund
• Account Verification
• Card Details (via GetCardDetails())

Note: The HMAC token is not generated during Confirm/Completion, Void, or Linked Refund operations, as these transaction types do not involve a physical card presentation.

Card In, Card Out Process

Stage 1 — Card In

• Perform a transaction to retrieve the tokenised card details (offline token).
  • This could be a pre-auth which would go online to the bank and check the card is valid (may add a small delay). This would be done using the StartTransaction() method.
  • Alternatively, use the method GetCardDetails() as this just reads the card details without going online to the bank and is therefore quicker.

Stage 2 — Card Out

Contact Card

• Start the transaction for an amount of zero.
• The transaction will pause after the CardDetailsEvent.
• Update the transaction amount using the ContinueTransaction() method.
  • The amount would be calculated by the integrator's backend. This is done by comparing the time the card was initially presented to the current time.

Contactless Card

• Start the transaction for an amount of zero.
• If a card is tapped, get the tokenised card details (offline token).
• Start a new transaction for the actual amount the customer should be charged.
  • The amount would be calculated by the integrator's backend. This is done by comparing the time the card was initially presented to the current time.

The reason why the amount cannot be changed for a contactless card is because the card has already authorised for that amount at the point of tap. Therefore, a second tap is required.

Supported Devices

The following devices support PaymentDevice HMAC Token generation and are compatible with Card In, Card Out. All devices must be injected with NMI's HMAC key prior to use.

HMAC Key Requirements

HMAC key injection is a mandatory prerequisite for offline tokenization. Keys are device-specific and must be arranged with the device distributor or manufacturer. NMI does not perform key injection directly.

Ingenico RAM Devices

• Keys are injected by the device manufacturer or distributor as part of the standard provisioning process.
• Contact your Ingenico distributor to confirm your devices have been injected with NMI's HMAC key before deployment.

Verifone VIPA Devices (Ux300 / Ux301)

• Key injection uses the VRK Package Method via the MX Downloader application.
• NMI's ANSI HMAC key package consists of a single key spread across 4 files, delivered as a .tgz archive containing a .tar file with crt and os folders. Ensure the package is in this format before injection or the key may not load correctly.
• Test and development key packages are available from NMI's internal distribution. Contact NMI Support for access.

Note: If you are unsure whether your devices have been injected with NMI's HMAC key, contact your device distributor or NMI Support before attempting to implement Card In, Card Out functionality.