Collect.js Card Type Detection

Overview

Collect.js includes automatic card type detection using BIN (Bank Identification Number) lookup, also known as IIN (Issuer Identification Number). This feature identifies whether a card is a credit card, debit card, or another card type during the payment data collection process. This information enables developers to implement intelligent surcharging systems that only apply surcharges to credit cards, helping ensure compliance with industry regulations and local requirements.

How It Works

When using Collect.js, developers receive a payment token through the standard callback mechanism. The callback response now includes a new category field that indicates the card type based on BIN lookup analysis performed automatically when the card data is collected.

The BIN lookup occurs transparently during the tokenization process—there are no additional API calls required. The card type information is determined by analyzing the first six digits of the card number (the BIN) against industry databases.

Response Format

The Collect.js callback response now includes the following additional field:

{
  "tokenType": "inline",
  "token": "SW8eBa72-jkaqt9-xyuEX2-DC8qceRbe6z6",
  "initiatedBy": {
    "isTrusted": true
  },
  "card": {
    "number": "411111******1111",
    "bin": "411111",
    "exp": "1030",
    "type": "visa",
    "category": "unknown",
    "hash": ""
  },
...
}

Category Values

credit
debit
prepaid
unknown

Implementation Guide

Step 1: Update Your Callback Handler

Modify your Collect.js callback function to access the new category field:

CollectJS.configure({
  fields: {
    cardNumber: {
      selector: "#card-number",
      title: "Card Number"
    },
    cardExpiration: {
      selector: "#card-expiration",
      title: "Card Expiration"
    },
    cvv: {
      selector: "#cvv",
      title: "CVV"
    }
  },
  callback: function(response) {
    if (response.token) {
      // Access the new category field from the card object
      const cardCategory = response.card.category;
      const token = response.token;

      // Use cardCategory to determine surcharge logic
      handlePaymentWithSurcharge(token, cardCategory);
    }
  }
});

Step 2: Implement Surcharge Logic

Use the card category to conditionally apply surcharges:

function handlePaymentWithSurcharge(token, cardCategory) {
  const baseAmount = 100.00; // Your base transaction amount
  let finalAmount = baseAmount;
  let surchargeApplied = false;
  
  // Only apply surcharge to credit cards
  if (cardCategory === "credit") {
    const surchargeRate = 0.03; // 3% surcharge rate (example)
    const surchargeAmount = baseAmount * surchargeRate;
    finalAmount = baseAmount + surchargeAmount;
    surchargeApplied = true;
    
    // Update UI to inform customer
    updateUISurchargeNotice(surchargeAmount, finalAmount);
  } else {
    // No surcharge for debit cards or other card types
    updateUINoSurcharge();
  }
  
  // Proceed with payment submission
  submitPayment(token, finalAmount, surchargeApplied);
}

Step 3: Update User Interface

Update your payment UI to show customers when a surcharge will be applied:

function updateUISurchargeNotice(surchargeAmount, finalAmount) {
  // Display surcharge information to customer
  document.getElementById("surcharge-notice").textContent = 
    `Credit card surcharge: $${surchargeAmount.toFixed(2)}`;
  document.getElementById("total-amount").textContent = 
    `Total: $${finalAmount.toFixed(2)}`;
  document.getElementById("surcharge-notice").style.display = "block";
}

function updateUINoSurcharge() {
  // Hide surcharge notice for debit cards
  document.getElementById("surcharge-notice").style.display = "none";
  document.getElementById("total-amount").textContent = 
    `Total: $${baseAmount.toFixed(2)}`;
}

Important Considerations

No Additional Configuration Required: The BIN lookup happens automatically, no additional API calls or setup needed.
Backward Compatibility: Existing Collect.js implementations continue to work. The category field is an addition to the existing callback response.
Compliance Responsibility: While this feature helps identify card types for surcharging, merchants remain responsible for ensuring compliance with all applicable regulations, including local surcharging laws, card network rules, and regional restrictions
Surcharge Calculations: This feature provides card type identification only. Integrators must implement their own surcharge calculation logic based on their business rules and compliance requirements.