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

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: ["expiryDate"]
    },
    serializers: [sdk.getCardSerializers().expiryDate()],
  }
)

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: "driversLicense",
      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: ["expiryDate"]
        },
        serializers: [sdk.getCardSerializers().expiryDate()],
      }
    )
    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().expiryDate()

Troubleshooting

"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​

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​

"Unauthorized" or "Invalid Token" Errors​

Form Fields Not Appearing​

Reveal Shows Nothing​