# UI SDK Reference

This document is the **authoritative reference** for the Nelnet Payment Services (NPS) UI SDK used to initialize and interact with the **Hosted Tokenization Iframe**.

It describes:

- Constructor options
- Instance methods
- Configuration objects
- Callback contracts
- Error handling


This page is intentionally **reference-focused**.
For conceptual guidance, see **Tokenization Overview** and **Hosted Tokenization Iframe**.

## Core Principle

div
strong
Key idea:
br

  The UI SDK controls the iframe. Your application controls the flow.

## SDK Initialization

### `new NPS(config)`

Creates a new UI SDK instance.

#### Required by NPS

| Option | Type | Description |
|  --- | --- | --- |
| `sessionToken` | `string` | Session token created server-side |
| `sessionId` | `string` | Session identifier |


#### Optional Callbacks

| Option | Type | Description |
|  --- | --- | --- |
| `onReady` | `function` | Fired when the iframe is ready |
| `onTokenizationComplete` | `function` | Fired when tokenization succeeds |
| `onError` | `function` | Fired on SDK or tokenization errors |



```js
const nps = new NPS({
  sessionToken: '<SESSION_TOKEN>',
  sessionId: '<SESSION_ID>',
  onReady: () => {},
  onTokenizationComplete: (result) => {},
  onError: (error) => {}
});
```

## Instance Methods

### `mount(container, options)`

Mounts the hosted tokenization iframe.

| Parameter | Type | Description |
|  --- | --- | --- |
| `container` | `string` | `HTMLElement` | Container selector or element |
| `options` | `object` | Mount configuration |



```js
nps.mount('#nps-container', {
  paymentMethod: 'card'
});
```

### `updatePaymentMethod(method)`

Switches the active payment method without remounting.

| Value | Description |
|  --- | --- |
| `card` | Credit or debit card |
| `ach` | ACH bank account |
| `applepay` | Apple Pay |
| `paypal` | PayPal / Venmo |



```js
nps.updatePaymentMethod('ach');
```

### `tokenize(data)`

Explicitly triggers tokenization.

div
strong
Important:
br

  Tokenization is never automatic. You must explicitly call 
code
tokenize()
.


```js
const result = await nps.tokenize({
  amount: 125.00,
  billingAddress: {
    name: 'Jane Smith',
    addressLine1: '123 Main St',
    postalCode: '68102',
    country: 'US'
  }
});
```

#### Returned Object

| Field | Description |
|  --- | --- |
| `token` | NPS payment token |
| `tokenType` | PAN, network token, or wallet token |
| `lastFour` | Last four digits |
| `bin` | Card BIN (if applicable) |
| `surcharge` | Surcharge calculation (if configured) |


### `destroy()`

Unmounts the iframe and releases resources.


```js
nps.destroy();
```

## Tokenization Data

### Required Fields

| Field | Description |
|  --- | --- |
| `amount` | Payment amount |
| `billingAddress` | Payer billing details (cards) |


### ACH-Specific Fields

| Field | Description |
|  --- | --- |
| `accountType` | `checking` or `savings` |


### Optional Fields

| Field | Description |
|  --- | --- |
| `metadata` | Merchant-defined metadata |


## Styling Configuration

Styling options affect **iframe contents only**.

### Theme & Layout

| Option | Values |
|  --- | --- |
| `theme` | `light`, `dark` |
| `labelStyle` | `stacked`, `floating`, `hidden` |
| `fieldLayout` | `stacked`, `inline`, `inline-split` |


### Colors & Typography

Styling supports full customization of:

- Fonts
- Field borders
- Focus states
- Error styles
- Wallet buttons


> Surrounding page layout is always merchant-owned.


## Callback Contracts

### `onReady()`

Called when the iframe is fully initialized.

### `onTokenizationComplete(result)`

Called after successful tokenization.

### `onError(error)`

Called on validation, session, or network errors.


```js
{
  code: 'SESSION_EXPIRED',
  message: 'Session token expired',
  fields: {}
}
```

## Common Errors

| Code | Description |
|  --- | --- |
| `VALIDATION_ERROR` | Invalid input |
| `SESSION_EXPIRED` | Session token expired |
| `TOKENIZATION_FAILED` | Tokenization failure |
| `SDK_ERROR` | Initialization error |


## Relationship to Payments

The UI SDK **never submits payments**.

After tokenization:

1. Send token to your backend
2. Submit payment via Payments API
3. Token participates in lifecycle management


## Summary

- UI SDK controls the hosted tokenization iframe
- Tokenization is always explicit
- Session tokens are browser-only
- Styling affects iframe only
- Tokens returned are safe to forward to backend