# NPS SDK Reference

div
div
h2
Complete SDK Reference
p
All variables, functions, options, and callbacks available to merchants
## Table of Contents

- [Constructor Options](#constructor-options)
- [Instance Methods](#instance-methods)
- [Mount Options](#mount-options)
- [Styling Options](#styling-options)
- [Display Options](#display-options)
- [Tokenization Data](#tokenization-data)
- [Callback Functions](#callback-functions)
- [Error Codes](#error-codes)
- [Payment Methods](#payment-methods)
- [Events](#events)


## Constructor Options

### `new NPS(config)`

Creates a new NPS SDK instance.

**Parameters:**

| Option | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| `sessionToken` | `string` | Yes | - | JWT session token from your backend |
| `sessionId` | `string` | Yes | - | Session ID from your backend |
| `onReady` | `function` | No | `() => {}` | Callback when SDK is initialized |
| `onTokenizationComplete` | `function` | No | `() => {}` | Callback when tokenization succeeds |
| `onError` | `function` | No | `() => {}` | Callback for error handling |


**Example:**


```javascript
const nps = new NPS({
    sessionToken: 'your_session_token',
    sessionId: 'your_session_id',
    onReady: () => console.log('SDK ready'),
    onTokenizationComplete: (result) => console.log('Token:', result.token),
    onError: (error) => console.error('Error:', error)
});
```

## Instance Methods

### `mount(containerSelector, options)`

Mounts the payment form iframe to the specified container.

**Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `containerSelector` | `string` or `HTMLElement` | Yes | CSS selector or DOM element (e.g., `'#payment-form'`) |
| `options` | `object` | No | Mount options (see [Mount Options](#mount-options)) |


**Returns:** `void`

**Example:**


```javascript
nps.mount('#payment-form', {
    paymentMethod: 'card',
    displayOptions: { showLabels: true },
    styling: { theme: 'light' }
});
```

### `updatePaymentMethod(method)`

Switches the payment method without remounting.

**Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `method` | `string` | Yes | Payment method: `'card'`, `'ach'`, or `'applepay'` |


**Returns:** `void`

**Example:**


```javascript
// Switch to ACH
nps.updatePaymentMethod('ach');

// Switch to card
nps.updatePaymentMethod('card');

// Switch to Apple Pay
nps.updatePaymentMethod('applepay');
```

### `tokenize(data)`

Tokenizes payment data and returns a payment token.

**Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `data` | `object` | Yes | Tokenization data (see [Tokenization Data](#tokenization-data)) |


**Returns:** `Promise<object>` - Resolves with tokenization result

**Example:**


```javascript
const result = await nps.tokenize({
    amount: 49.99,
    cardholderName: 'John Doe',
    billingAddress: {
        name: 'John Doe',
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        postalCode: '90210',
        country: 'US'
    },
    metadata: {
    }
});

console.log(result.token); // Payment token
```

**Result Object:**

| Property | Type | Description |
|  --- | --- | --- |
| `token` | `string` | Payment token to send to backend |


### `destroy()`

Removes the iframe and cleans up resources.

**Parameters:** None

**Returns:** `void`

**Example:**


```javascript
nps.destroy();
```

## Mount Options

The `mount()` method accepts an options object with the following properties:

**Options Object:**

| Option | Type | Required | Description |
|  --- | --- | --- | --- |
| `paymentMethod` | `string` | No | `'card'`, `'ach'`, or `'applepay'` (default: `'card'`) |
| `displayOptions` | `object` | No | Display options (see [Display Options](#display-options)) |
| `styling` | `object` | No | Styling options (see [Styling Options](#styling-options)) |
| `width` | `string` | No | Iframe width (e.g., `'100%'`, `'500px'`, `'auto'`) |


**Example:**


```javascript
nps.mount('#payment-form', {
    paymentMethod: 'card',
    width: '100%',
    displayOptions: {
        showLabels: true,
        showIcons: true,
        showErrors: true
    },
    styling: {
        theme: 'light',
        colors: { focusBorder: '#3B82F6' }
    }
});
```

## Display Options

| Option | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| `showLabels` | `boolean` | No | `true` | Show field labels |
| `showIcons` | `boolean` | No | `true` | Show card brand icons |
| `showErrors` | `boolean` | No | `true` | Show validation error messages |
| `showPlaceholders` | `boolean` | No | `true` | Show placeholder text in inputs |
| `showRequiredIndicator` | `boolean` | No | `true` | Show asterisk (*) for required fields |
| `showSecurityCodeIndicator` | `boolean` | No | `true` | Show CVV/CVC security code icon |


**Example:**


```javascript
displayOptions: {
    showLabels: true,
    showIcons: true,
    showErrors: true,
    showPlaceholders: true,
    showRequiredIndicator: true,
    showSecurityCodeIndicator: true
}
```

## Styling Options

### Theme Options

| Option | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| `theme` | `string` | No | `'light'` | `'light'` or `'dark'` |
| `labelStyle` | `string` | No | `'stacked'` | `'stacked'`, `'floating'`, or `'hidden'` |
| `fieldStyle` | `string` | No | `'outlined'` | `'outlined'`, `'filled'`, or `'underlined'` |
| `fieldLayout` | `string` | No | `'stacked'` | `'stacked'`, `'inline-split'`, or `'inline'` (Card only) |


### Typography Options

| Option | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| `fontFamily` | `string` | No | `'Inter'` | Font family (e.g., `'Inter, sans-serif'`) |
| `fontSize` | `number` or `string` | No | `15` | Input font size in pixels |
| `labelFontSize` | `number` or `string` | No | `14` | Label font size in pixels |
| `labelFontWeight` | `number` | No | `500` | Label font weight (100-900) |
| `helpTextFontSize` | `number` or `string` | No | `14` | Help text font size in pixels |
| `helpTextFontWeight` | `number` | No | `400` | Help text font weight (100-900) |
| `errorFontSize` | `number` or `string` | No | `12` | Error message font size in pixels |


### Color Options

| Option | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| `colors.label` | `string` | No | `'#5A5E66'` | Label text color |
| `colors.border` | `string` | No | `'#C4C8CC'` | Input border color |
| `colors.focusBorder` | `string` | No | `'#3B82F6'` | Border color when focused |
| `colors.error` | `string` | No | `'#D32F2F'` | Error text and border color |
| `colors.text` | `string` | No | `'#000000'` | Input text color |
| `colors.background` | `string` | No | `'#FFFFFF'` | Input background color (light theme) |
| `colors.filledBackground` | `string` | No | `'#F3F4F6'` | Background for filled field style |
| `colors.helpText` | `string` | No | `'#9CA3AF'` | Help text and placeholder color |
| `colors.buttonBackground` | `string` | No | `'#000'` | Button background color (Apple Pay) |
| `colors.buttonColor` | `string` | No | `'white'` | Button text color |
| `colors.buttonHoverBackground` | `string` | No | `'#1a1a1a'` | Button hover background |
| `colors.buttonBorderColor` | `string` | No | `transparent` | Button border color |


### Spacing & Dimension Options

| Option | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| `spacing` | `number` | No | `12` | Spacing between elements in pixels (0-32px) |
| `borderRadius` | `number` or `string` | No | `4` | Border radius in pixels (0-32px) |
| `borderWidth` | `number` | No | `1` | Border width in pixels (0-32px) |
| `inputHeight` | `number` | No | `36` | Input field height in pixels (min 20px) |
| `inputPadding` | `string` | No | `'10px 12px'` | Input padding (CSS format) |
| `iframeWidth` | `string` | No | `'100%'` | Iframe width (e.g., `'100%'`, `'500px'`) |


**Complete Example:**


```javascript
styling: {
    theme: 'light',
    labelStyle: 'stacked',
    fieldStyle: 'outlined',
    fieldLayout: 'stacked',
    fontFamily: 'Inter, sans-serif',
    fontSize: 15,
    labelFontSize: 14,
    labelFontWeight: 500,
    helpTextFontSize: 14,
    helpTextFontWeight: 400,
    colors: {
        label: '#5A5E66',
        border: '#C4C8CC',
        focusBorder: '#3B82F6',
        error: '#D32F2F',
        text: '#000000',
        background: '#FFFFFF',
        helpText: '#9CA3AF',
        filledBackground: '#F3F4F6'
    },
    spacing: 12,
    borderRadius: 4,
    borderWidth: 1,
    inputHeight: 36,
    inputPadding: '10px 12px',
    iframeWidth: '100%',
    focusShadow: '0 0 0 3px rgba(59, 130, 246, 0.1)'
}
```

## Tokenization Data

The `tokenize()` method accepts a data object with the following structure:

**Required Fields:**

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `amount` | `number` | Yes | Payment amount (e.g., `49.99` for $49.99) |
| `cardholderName` | `string` | Yes | Full cardholder name (e.g., `'John Doe'`) |
| `billingAddress` | `object` | Yes | Billing address object (see below) |


**Billing Address Object:**

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `name` | `string` | Yes | Full name |
| `street` | `string` | Yes | Street address |
| `city` | `string` | Yes | City |
| `state` | `string` | Yes | State/Province (2-letter code for US) |
| `postalCode` | `string` | Yes | ZIP/Postal code |
| `country` | `string` | Yes | Country code (e.g., `'US'`) |


**Optional Fields:**

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `accountType` | `string` | For ACH | Account type: `'checking'` or `'savings'` (required for ACH payments) |
| `metadata` | `object` | No | Additional metadata |


**Example:**


```javascript
const result = await nps.tokenize({
    amount: 49.99,
    cardholderName: 'John Doe',
    billingAddress: {
        name: 'John Doe',
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        postalCode: '90210',
        country: 'US'
    },
    metadata: {
    }
});
```

## Callback Functions

### `onReady()`

Called when the SDK is initialized and ready to use.

**Parameters:** None

**Example:**


```javascript
const nps = new NPS({
    sessionToken: 'token',
    sessionId: 'session_123',
    onReady: () => {
        console.log('SDK is ready!');
        // Enable submit button, show form, etc.
    }
});
```

### `onTokenizationComplete(result)`

Called when tokenization succeeds.

**Parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `result` | `object` | Tokenization result (see [Tokenization Result](#tokenization-result)) |


**Example:**


```javascript
const nps = new NPS({
    sessionToken: 'token',
    sessionId: 'session_123',
    onTokenizationComplete: (result) => {
        console.log('Token:', result.token);
        
        // Send token to your backend
        fetch('/api/process-payment', {
            method: 'POST',
            body: JSON.stringify({ token: result.token })
        });
    }
});
```

**Tokenization Result:**

| Property | Type | Description |
|  --- | --- | --- |
| `token` | `string` | Payment token (send to backend) |


### `onError(error)`

Called when an error occurs.

**Parameters:**

| Parameter | Type | Description |
|  --- | --- | --- |
| `error` | `object` | Error object (see [Error Codes](#error-codes)) |


**Example:**


```javascript
const nps = new NPS({
    sessionToken: 'token',
    sessionId: 'session_123',
    onError: (error) => {
        console.error('Error code:', error.code);
        console.error('Error message:', error.message);
        
        switch(error.code) {
            case 'VALIDATION_ERROR':
                // Show validation errors to user
                break;
            case 'SESSION_EXPIRED':
                // Refresh session token
                break;
            case 'NETWORK_ERROR':
                // Retry request
                break;
        }
    }
});
```

## Error Codes

| Code | Description | Solution |
|  --- | --- | --- |
| `VALIDATION_ERROR` | Invalid input in payment fields | Check form fields and show errors to user |
| `SESSION_EXPIRED` | Session token has expired | Request new session token from backend |
| `NETWORK_ERROR` | Network connectivity issue | Retry request or check connection |
| `TOKENIZATION_FAILED` | Tokenization request failed | Check error message and retry |
| `SDK_ERROR` | SDK initialization or mount error | Ensure SDK is properly initialized |


**Error Object Structure:**


```javascript
{
    code: 'VALIDATION_ERROR',
    message: 'Invalid card number',
    fields: {
        cardNumber: 'Invalid card number'
    }
}
```

## Payment Methods

| Value | Description |
|  --- | --- |
| `'card'` | Credit or debit card |
| `'ach'` | ACH bank transfer |
| `'applepay'` | Apple Pay |


**Example:**


```javascript
// Mount with card payment
nps.mount('#payment-form', { paymentMethod: 'card' });

// Switch to ACH
nps.updatePaymentMethod('ach');

// Switch to Apple Pay
nps.updatePaymentMethod('applepay');
```

## Events

### Custom Events (Optional)

You can also use custom events instead of callbacks:

**Mount Event:**


```javascript
window.addEventListener('nps-mount', (event) => {
    const { containerSelector, options } = event.detail;
    // Mount will be called automatically
});

window.dispatchEvent(new CustomEvent('nps-mount', {
    detail: {
        containerSelector: '#payment-form',
        options: { paymentMethod: 'card' }
    }
}));
```

**Update Payment Method Event:**


```javascript
window.addEventListener('nps-update-payment-method', (event) => {
    const { method } = event.detail;
    // Update will be called automatically
});

window.dispatchEvent(new CustomEvent('nps-update-payment-method', {
    detail: { method: 'ach' }
}));
```

**Tokenize Event:**


```javascript
window.addEventListener('nps-tokenization-complete', (event) => {
    const result = event.detail;
    console.log('Token:', result.token);
});

window.addEventListener('nps-tokenization-error', (event) => {
    const error = event.detail;
    console.error('Error:', error);
});

window.dispatchEvent(new CustomEvent('nps-tokenize', {
    detail: {
        additionalData: {
            amount: 49.99,
            cardholderName: 'John Doe',
            billingAddress: { /* ... */ }
        }
    }
}));
```

## Complete Example


```javascript
// 1. Initialize SDK
const nps = new NPS({
    sessionToken: await fetchSessionToken(),
    sessionId: 'session_123',
    onReady: () => console.log('Ready'),
    onTokenizationComplete: (result) => {
        console.log('Token:', result.token);
        // Send to backend
    },
    onError: (error) => console.error('Error:', error)
});

// 2. Mount payment form
nps.mount('#payment-form', {
    paymentMethod: 'card',
    width: '100%',
    displayOptions: {
        showLabels: true,
        showIcons: true,
        showErrors: true,
        showPlaceholders: true,
        showRequiredIndicator: true,
        showSecurityCodeIndicator: true
    },
    styling: {
        theme: 'light',
        labelStyle: 'stacked',
        fieldStyle: 'outlined',
        fieldLayout: 'stacked',
        fontFamily: 'Inter, sans-serif',
        fontSize: 15,
        labelFontSize: 14,
        labelFontWeight: 500,
        colors: {
            label: '#5A5E66',
            border: '#C4C8CC',
            focusBorder: '#3B82F6',
            error: '#D32F2F',
            text: '#000000',
            helpText: '#9CA3AF'
        },
        spacing: 12,
        borderRadius: 4,
        borderWidth: 1,
        inputHeight: 36,
        iframeWidth: '100%'
    }
});

// 3. Switch payment method
nps.updatePaymentMethod('ach');

// 4. Tokenize payment
const result = await nps.tokenize({
    amount: 49.99,
    cardholderName: 'John Doe',
    billingAddress: {
        name: 'John Doe',
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        postalCode: '90210',
        country: 'US'
    },
    accountType: 'checking', // Required for ACH
    metadata: {
    }
});

// 5. Clean up
nps.destroy();
```

## Support Resources

div
div
div
h3
Need Help?
div
div
Technical Support
a
NPSTechSupport@nelnet.net