JavaScript / Node.js SDK

Overview

The JavaScript SDK enables secure collection and reveal of sensitive data in web applications and Node.js backends.

Requirements

Browser: Requires a bundler (Webpack, Vite, Rollup, or Parcel)
Node.js: Can be used directly without bundler
Browser Compatibility: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Installation

After downloading the SDK package, install it using the .tgz file:

npm install ./secure-connect-sdk-1.0.0.tgz

Or if using yarn:

yarn add ./secure-connect-sdk-1.0.0.tgz

Browser Setup (Required)

For browser-based applications (React, Vue, Angular, vanilla JavaScript), the Show module script must be available as a static asset served from your application's public directory. This script provides the secure data reveal functionality and must load before your application code.

1. Copy the Show Module to your public directory

Run this command from your project root after installing the SDK:

cp node_modules/secure-connect-sdk/dist/show-module.js public/

Why is this step needed?

Build bundlers (Vite, Webpack, Parcel, etc.) do not include node_modules in the production build output. The Show module must be served as a static file, so it needs to live in your project's public/ directory (or equivalent static assets folder) to be available at runtime.

This file only needs to be copied once. It does not change between SDK releases unless you are explicitly notified of a Show module version update.

2. Add the script tag to your HTML

Include the script in your index.html before your application code loads:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your App</title>

    <!-- Load Show module for secure data reveal -->
    <script
      type="text/javascript"
      src="/show-module.js"
    ></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Configuration

SDK Initialization

import { SecureConnectSDK, SDKOperation } from 'secure-connect-sdk'

// 1. Fetch JWT token from Gateway API
const response = await fetch('https://api.connect.financial/v1/vault/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'API_KEY',
  },
  body: JSON.stringify({ userId: 'USER_ID' }),
})
const { data } = await response.json()
const jwtToken = data.token

// 2. Initialize SDK
const sdk = new SecureConnectSDK({
  gatewayUrl: 'https://api.connect.financial'
})

// 3. Load Collect with JWT token
await sdk.loadCollect(jwtToken)

Revealing Card Data

Use createSecureVisualizationManager to securely display card information:

Reveal Card PAN

const authHeaders = {
  "Content-Type": "application/json",
  "Authorization": `Bearer ${jwtToken}`
}

const panManager = sdk.createSecureVisualizationManager(
  SDKOperation.REVEAL_CARD_PAN,
  {
    name: "card-pan-reveal",
    htmlWrapper: "text",
    headers: authHeaders,
    payload: {
      type: "card",
      cardId: "your-card-uuid",
      fields: ["pan"]
    },
    serializers: [sdk.getCardSerializers().panWithDashes()],
  }
)

panManager.render("#card-pan-container")

Reveal Card CVV

const cvvManager = sdk.createSecureVisualizationManager(
  SDKOperation.REVEAL_CARD_CVV,
  {
    name: "card-cvv-reveal",
    htmlWrapper: "text",
    headers: authHeaders,
    payload: {
      type: "card",
      cardId: "your-card-uuid",
      fields: ["cvv"]
    }
  }
)

cvvManager.render("#card-cvv-container")

Reveal Card Expiry

const expiryManager = sdk.createSecureVisualizationManager(
  SDKOperation.REVEAL_CARD_EXPIRY,
  {
    name: "card-expiry-reveal",
    htmlWrapper: "text",
    headers: authHeaders,
    payload: {
      type: "card",
      cardId: "your-card-uuid",
      fields: ["expiry"]
    },
    serializers: [sdk.getCardSerializers().expiryFull()],
  }
)

expiryManager.render("#card-expiry-container")

Revealing Document Data

const ssnManager = sdk.createSecureVisualizationManager(
  SDKOperation.REVEAL_DOCUMENT_SSN,
  {
    name: "ssn-reveal",
    htmlWrapper: "text",
    headers: authHeaders,
    payload: {
      type: "document",
      documentType: "ssn"
    }
  }
)

ssnManager.render("#customer-ssn")

Collecting Document Data

Use createSecureIframeForm to securely collect sensitive document information:

Collect SSN

const ssnForm = sdk.createSecureIframeForm(
  SDKOperation.SUBMIT_DOCUMENT_SSN,
  {
    selector: "#kyc-ssn-collect",
    type: "text",
    name: "documentNumber",
    placeholder: "Enter SSN (XXX-XX-XXXX)",
    validations: ["required"],
  },
  (state) => {
    // Handle field state changes
    console.log("Field state:", state)
  }
)

// Submit the form
ssnForm.submitWithOperation(
  {
    data: (formData) => ({
      documentType: "ssn",
      documentToken: formData.documentNumber,
    }),
    serialization: "JSON",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${jwtToken}`,
    },
  },
  (status, data) => {
    console.log("Success:", data.json)
  },
  (errors) => {
    console.error("Errors:", errors)
  }
)

Collect Driver's License

const licenseForm = sdk.createSecureIframeForm(
  SDKOperation.SUBMIT_DOCUMENT_DRIVERS_LICENCE,
  {
    selector: "#kyc-license-collect",
    type: "text",
    name: "documentNumber",
    placeholder: "Enter Driver's License Number",
    validations: ["required"],
  },
  (state) => console.log("Field state:", state)
)

licenseForm.submitWithOperation(
  {
    data: (formData) => ({
      documentType: "license",
      documentToken: formData.documentNumber,
    }),
    serialization: "JSON",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${jwtToken}`,
    },
  },
  (status, data) => console.log("Success:", data.json),
  (errors) => console.error("Errors:", errors)
)

React Integration Example

import React, { useEffect, useState } from 'react'
import { SecureConnectSDK, SDKOperation } from 'secure-connect-sdk'

function CardReveal({ cardId }) {
  const [sdk, setSdk] = useState(null)
  const [jwtToken, setJwtToken] = useState(null)

  useEffect(() => {
    async function initSDK() {
      // Fetch JWT token
      const response = await fetch('https://api.connect.financial/v1/vault/token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: 'API_KEY',
        },
        body: JSON.stringify({ userId: 'USER_ID' }),
      })
      const { data } = await response.json()
      setJwtToken(data.token)

      // Initialize SDK
      const sdkInstance = new SecureConnectSDK({
        gatewayUrl: 'https://api.connect.financial'
      })
      await sdkInstance.loadCollect(data.token)
      setSdk(sdkInstance)
    }

    initSDK()
  }, [])

  useEffect(() => {
    if (!sdk || !jwtToken) return

    const authHeaders = {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${jwtToken}`
    }

    // Render card PAN
    const panManager = sdk.createSecureVisualizationManager(
      SDKOperation.REVEAL_CARD_PAN,
      {
        name: "card-pan",
        htmlWrapper: "text",
        headers: authHeaders,
        payload: {
          type: "card",
          cardId: cardId,
          fields: ["pan"]
        },
        serializers: [sdk.getCardSerializers().panWithDashes()],
      }
    )
    panManager.render("#card-pan")

    // Render card CVV
    const cvvManager = sdk.createSecureVisualizationManager(
      SDKOperation.REVEAL_CARD_CVV,
      {
        name: "card-cvv",
        htmlWrapper: "text",
        headers: authHeaders,
        payload: {
          type: "card",
          cardId: cardId,
          fields: ["cvv"]
        }
      }
    )
    cvvManager.render("#card-cvv")

    // Render card expiry
    const expiryManager = sdk.createSecureVisualizationManager(
      SDKOperation.REVEAL_CARD_EXPIRY,
      {
        name: "card-expiry",
        htmlWrapper: "text",
        headers: authHeaders,
        payload: {
          type: "card",
          cardId: cardId,
          fields: ["expiry"]
        },
        serializers: [sdk.getCardSerializers().expiryFull()],
      }
    )
    expiryManager.render("#card-expiry")

  }, [sdk, jwtToken, cardId])

  return (
    <div className="card-details">
      <div className="field">
        <label>Card Number</label>
        <div id="card-pan"></div>
      </div>
      <div className="field">
        <label>CVV</label>
        <div id="card-cvv"></div>
      </div>
      <div className="field">
        <label>Expiry</label>
        <div id="card-expiry"></div>
      </div>
    </div>
  )
}

export default CardReveal

Available Operations

Card Operations

Operation	Type	Description
`SDKOperation.REVEAL_CARD_PAN`	Reveal	Reveal card number
`SDKOperation.REVEAL_CARD_CVV`	Reveal	Reveal CVV
`SDKOperation.REVEAL_CARD_EXPIRY`	Reveal	Reveal expiry date

Document Operations

Operation	Type	Description
`SDKOperation.SUBMIT_DOCUMENT_ID`	Collect	Tokenize document ID
`SDKOperation.SUBMIT_DOCUMENT_SSN`	Collect	Tokenize SSN
`SDKOperation.SUBMIT_DOCUMENT_DRIVERS_LICENCE`	Collect	Tokenize driver's license
`SDKOperation.SUBMIT_DOCUMENT_PASSPORT`	Collect	Tokenize passport
`SDKOperation.REVEAL_DOCUMENT_ID`	Reveal	Reveal document ID
`SDKOperation.REVEAL_DOCUMENT_SSN`	Reveal	Reveal SSN
`SDKOperation.REVEAL_DOCUMENT_DRIVERS_LICENCE`	Reveal	Reveal driver's license
`SDKOperation.REVEAL_DOCUMENT_PASSPORT`	Reveal	Reveal passport

Card Serializers

Format revealed card data using built-in serializers:

// PAN with dashes: 4111-1111-1111-1111
sdk.getCardSerializers().panWithDashes()

// PAN with spaces: 4111 1111 1111 1111
sdk.getCardSerializers().panWithSpaces()

// Expiry date: MM/YY
sdk.getCardSerializers().expiryFull()

Troubleshooting

"SecureConnectShow is not defined" Error

This error means the show-module.js script was not loaded before your application code ran. Two common causes:

Script tag missing: Add it to index.html as described in Browser Setup.

File not in public directory: The script tag references /show-module.js but the file was never copied from node_modules. Run:

cp node_modules/secure-connect-sdk/dist/show-module.js public/

"Unauthorized" or "Invalid Token" Errors

JWT token may be expired or invalid. Regenerate the token via POST /v1/vault/token with a valid API key.

Form Fields Not Appearing

Ensure await sdk.loadCollect(jwtToken) completes before creating forms
Verify the DOM selector exists when createSecureIframeForm is called
Check browser console for errors

Reveal Shows Nothing

Check the Network tab in browser DevTools
Verify /v1/vault/show returns the expected JSON structure
Ensure cardId or documentType is valid

Overview​

Requirements​

Installation​

Browser Setup (Required)​

1. Copy the Show Module to your public directory​

2. Add the script tag to your HTML​

Configuration​

SDK Initialization​

Revealing Card Data​

Reveal Card PAN​

Reveal Card CVV​

Reveal Card Expiry​

Revealing Document Data​

Collecting Document Data​

Collect SSN​

Collect Driver's License​

React Integration Example​

Available Operations​

Card Operations​

Document Operations​

Card Serializers​

Troubleshooting​

"SecureConnectShow is not defined" Error​

"Unauthorized" or "Invalid Token" Errors​

Form Fields Not Appearing​

Reveal Shows Nothing​