VDT SDK

TypeScript SDK for Visa Data Tokens and Signals API

Installation

npm install vdt-sdk

Usage

import { VDTClient } from 'vdt-sdk';

const client = new VDTClient({
  userId: 'your-user-id',
  password: 'your-password',
  keyId: 'your-key-id',
  timeout: 30000
});

const token = await client.tokens.create({
  consentID: '529ae111-7cd6-4996-b421-347a172f257b',
  consentCaptureDateTime: '2025-09-17T19:02:14Z',
  consentExpirationDateTime: '2026-12-31T23:59:59Z',
  cards: [
    {
      enrollmentType: 'PAN',
      enrollmentValue: '4242424242424242'
    }
  ]
});

const signal = await client.signals.behavioral.getCategorySpendMomentum(
  token.dataToken,
  {
    category: 'restaurants',
    paymentChannel: 'card_present',
    paymentLocation: 'domestic'
  }
);

console.log(signal.signalValue.categoryEngagement);
console.log(signal.signalValue.spendGrowth);

API Reference

VDTClient

Main client class for interacting with the VDT API.

Constructor

new VDTClient(config: SDKConfig)

Parameters:

• config.userId (string, required): Your user ID for Basic Authentication
• config.password (string, required): Your password for Basic Authentication
• config.keyId (string, required): Your API key ID
• config.baseUrl (string, optional): Base URL for the API (default: https://revocable-overvaliantly-emmalyn.ngrok-free.app/visa/personalization-api/v1)
• config.timeout (number, optional): Request timeout in milliseconds (default: 30000)

Tokens Resource

create(request: CreateTokenRequest): Promise

Create a new data token with consent and card enrollment information.

const token = await client.tokens.create({
  consentID: '529ae111-7cd6-4996-b421-347a172f257b',
  consentCaptureDateTime: '2025-09-17T19:02:14Z',
  consentExpirationDateTime: '2026-12-31T23:59:59Z',
  cards: [
    {
      enrollmentType: 'PAN',
      enrollmentValue: '4242424242424242'
    }
  ],
  consentSource: 'CLIENT'
});

Parameters:

• consentID (string, required): Unique consent identifier
• consentCaptureDateTime (string, required): ISO 8601 datetime when consent was captured
• consentExpirationDateTime (string, required): ISO 8601 datetime when consent expires
• cards (array, required): Array of card enrollments (at least one required)
  • enrollmentType: Must be 'PAN'
  • enrollmentValue: 13-19 digit card number
• consentSource (string, optional): Source of consent (default: 'CLIENT')

Returns: DataToken object with dataToken field containing the token ID.

get(dataToken: string): Promise

Retrieve an existing data token by its token value.

const token = await client.tokens.get('token_123');

revoke(dataToken: string): Promise

Revoke a data token.

await client.tokens.revoke('token_123');

Behavioral Signals Resource

getCategorySpendMomentum(dataTokenID: string, params?: CategorySpendMomentumParams): Promise

Get category spend momentum signal for a data token.

// Without parameters (all categories)
const signal = await client.signals.behavioral.getCategorySpendMomentum(
  'token_123'
);

// With specific category
const signal = await client.signals.behavioral.getCategorySpendMomentum(
  'token_123',
  {
    category: 'restaurants',
    paymentChannel: 'card_present',
    paymentLocation: 'domestic'
  }
);

Parameters:

• dataTokenID (string): The data token ID
• params (CategorySpendMomentumParams, optional): Signal parameters
  • category (MerchantCategory, optional): The merchant category
  • paymentChannel (PaymentChannel, optional): Payment channel filter
  • paymentLocation (PaymentLocation, optional): Payment location filter

Merchant Categories: airlines, apparel_and_accessories, automotive, business_to_business, department_stores, direct_marketing, discount_stores, drugstores_and_pharmacies, education_and_government, electronics, entertainment, food_and_grocery, fuel, retail_goods, retail_services, health_care, home_improvement_supply, insurance, lodging, professional_services, quick_service_restaurant, restaurants, telecom_and_utilities, transportation, travel_services, vehicle_rental, wholesale_clubs, online_marketplaces

Payment Channels: card_not_present, card_present, all

Payment Locations: international, domestic, all

Response:

{
  signalName: 'behavioral.category_spend_momentum',
  signalValue: {
    categoryEngagement: 'CONSISTENTLY_ENGAGED' | 'NEWLY_ENGAGED' | 'RECENTLY_ENGAGED' | 'DORMANT' | 'LAPSED' | 'NEVER_ENGAGED' | null,
    spendGrowth: 'UP' | 'DOWN' | 'FLAT' | null
  }
}

Error Handling

The SDK provides custom error classes for different error scenarios:

import {
  VDTError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NotFoundError,
  ServerError
} from 'vdt-sdk';

try {
  const token = await client.tokens.create({ pan: 'INVALID' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed. Check your userId and password.');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded. Retry after:', error.retryAfter);
  }
}

Development

Build

npm run build

Test

npm test

Test with Coverage

npm run test:coverage

Test Watch Mode

npm run test:watch

License

ISC