Skip to main content

Allowlisting BIN Ranges

Updated

Table of Contents

  1. Overview
  2. Prerequisites
  3. Submitting an Allowlist for Approval
  4. Retrieving Allowlisted Card Data

 

Overview

Allowlisting is a security feature that enables pre-approved card data to be returned in plain text via the NMI Payment Device SDK. It is primarily used for non-payment card data, such as loyalty or membership cards, which are read via the device's magnetic stripe reader.

When an allowlist is approved and deployed to a device via TMS, the Payment Device SDK will return plain text Track 2 data for cards whose BIN (Bank Identification Number) range falls within the allowlisted range. This allows integrators to read non-payment card data — such as loyalty cards, transit passes, or membership cards — without the data being encrypted or tokenised.

Important limitations:

  • Allowlisting is only supported via the magnetic stripe reader. Chip and contactless card reads are not supported.
  • Allowlisting requests for actual payment cards will be denied for security reasons. BIN ranges must not overlap with any known payment card ranges.
  • The allowlist is delivered to devices as a signed file via a TMS update and must be approved by the hardware manufacturer before deployment.

Prerequisites

Payment Device SDK

  • A supported version of Payment Device SDK for Windows & Linux, Android, or iOS is required. Check the NMI Developer Portal to confirm your device supports allowlisting.

TMS

  • Allowlist deployment is managed via TMS. The signed allowlist file is delivered to your device estate through a TMS update once approved.

Device

  • The target device(s) must support the Card Allow Listing feature. Verify support against the feature matrix for your device and SDK platform before submitting a request.

 

Submitting an Allowlist for Approval

To enable allowlisting on a payment device, the following information must be provided to NMI Support. The process requires secure approval from the hardware manufacturer and may take several days to complete.

  1. Provide BIN Range(s)

    • Supply the BIN range(s) to be allowlisted. These must not be associated with any payment card scheme.
    • Example format:
    123456 0000 0000 (start) - 123456 9999 9999 (end)
  2. Confirm Card Number Length
    • Specify the expected card number length. This is typically 12–16 digits, depending on your use case.
  3. Identify the Payment Device(s)
    • Provide the make and model of the device(s) requiring the allowlist. Confirm that the device supports allowlisting via the NMI Developer Portal.
  4. Specify SDK Platform
    • Indicate the SDK platform used for integration — for example: Windows & Linux, Android, or iOS.
  5. Define Application Scope
    • Specify whether the allowlist applies to a specific merchant or to an entire device estate.
  6. Submit to NMI for Approval
    • Submit all of the above details via the NMI Support Form.
    • The allowlisting process includes:
      • Compilation of the allowlist
      • Secure approval by the hardware manufacturer
      • Delivery of a signed allowlist file via TMS update to your device estate

Note: The allowlisting process may take several days, as it requires secure approval from the hardware manufacturer to maintain data integrity.

 

Retrieving Allowlisted Card Data

Once the allowlist is approved and deployed to your device(s) via TMS, plain text Track 2 data is returned through the Payment Device SDK when a card within the allowlisted BIN range is swiped.

Use the CardDetailsEvent callback to capture the plain text Track 2 data via the Track2ClearText parameter key:

Response response = ClientHelper.getCardDetails(null);

// Callback when card is read
void cardDetailsEvent(EventParameters eventParameters) {
    String track2ClearText = eventParameters.getValue(ParameterKeys.Track2ClearText);
    // Handle the allowlisted card data as needed
}

The Track2ClearText parameter will contain the plain text Track 2 string for any card whose BIN falls within the approved allowlist range. Cards outside this range will continue to be handled via standard encryption.

Note: Allowlisted data is only returned for magnetic stripe reads. If a card is inserted (chip) or tapped (contactless), the allowlist will not apply and the data will be encrypted as normal.