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.
The UI SDK controls the iframe. Your application controls the flow.
Creates a new UI SDK instance.
| Option | Type | Description |
|---|---|---|
sessionToken | string | Session token created server-side |
sessionId | string | Session identifier |
| 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 |
const nps = new NPS({
sessionToken: '<SESSION_TOKEN>',
sessionId: '<SESSION_ID>',
onReady: () => {},
onTokenizationComplete: (result) => {},
onError: (error) => {}
});Mounts the hosted tokenization iframe.
| Parameter | Type | Description |
|---|---|---|
container | string | HTMLElement | Container selector or element |
options | object | Mount configuration |
nps.mount('#nps-container', {
paymentMethod: 'card'
});Switches the active payment method without remounting.
| Value | Description |
|---|---|
card | Credit or debit card |
ach | ACH bank account |
applepay | Apple Pay |
paypal | PayPal / Venmo |
nps.updatePaymentMethod('ach');Explicitly triggers tokenization.
Tokenization is never automatic. You must explicitly call
tokenize().
const result = await nps.tokenize({
amount: 125.00,
billingAddress: {
name: 'Jane Smith',
addressLine1: '123 Main St',
postalCode: '68102',
country: 'US'
}
});| 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) |
Unmounts the iframe and releases resources.
nps.destroy();| Field | Description |
|---|---|
amount | Payment amount |
billingAddress | Payer billing details (cards) |
| Field | Description |
|---|---|
accountType | checking or savings |
| Field | Description |
|---|---|
metadata | Merchant-defined metadata |
Styling options affect iframe contents only.
| Option | Values |
|---|---|
theme | light, dark |
labelStyle | stacked, floating, hidden |
fieldLayout | stacked, inline, inline-split |
Styling supports full customization of:
- Fonts
- Field borders
- Focus states
- Error styles
- Wallet buttons
Surrounding page layout is always merchant-owned.
Called when the iframe is fully initialized.
Called after successful tokenization.
Called on validation, session, or network errors.
{
code: 'SESSION_EXPIRED',
message: 'Session token expired',
fields: {}
}| Code | Description |
|---|---|
VALIDATION_ERROR | Invalid input |
SESSION_EXPIRED | Session token expired |
TOKENIZATION_FAILED | Tokenization failure |
SDK_ERROR | Initialization error |
The UI SDK never submits payments.
After tokenization:
- Send token to your backend
- Submit payment via Payments API
- Token participates in lifecycle management
- 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