# SDK Integration Guide
div
h2
NPS JavaScript SDK
p
Detailed instructions for integrating the NPS JavaScript SDK into your web application
## Integration Steps
div
div
div
1
strong
Install SDK
Include the NPS SDK directly from our CDN:
```html
```
div
div
2
strong
Setup Backend Authentication
div
Before using the SDK, your backend must obtain a session token from the NPS API.
**Step 2.1: Obtain Credentials**
- Obtain your secret from NPS
- Store credentials securely
**Step 2.2: Create JWT Authentication Token**
All NPS API requests require JWT (JSON Web Token) authentication with:
- **Algorithm**: HS512 (HMAC-SHA512)
- **Header**: `Authorization: Bearer `
- **Required Claims**:
- `sub`: Your API Key ID
- `iat`: Issued at timestamp (current time)
- `exp`: Expiration timestamp
```javascript
const jwt = require('jsonwebtoken');
function createAuthToken() {
const payload = {
sub: process.env.NPS_API_KEY_ID,
iat: Math.floor(...),
exp: Math.floor(...)
};
return jwt.sign(payload, process.env.NPS_API_KEY, {
algorithm: 'HS512'
});
}
```
div
div
3
strong
Create Payment Session Endpoint
div
Create a backend endpoint that requests a payment session from the NPS API:
```javascript
app.post('', async (req, res) => {
const authToken = createAuthToken();
const response = await fetch('', {
method: 'POST',
headers: {
'Authorization': `Bearer ${authToken}`,
'Content-Type': 'application/json'
}
});
const data = await response.json();
res.json({
sessionId: data.session.id,
sessiontoken: data.session.token,
expiresAt: data.session.expiresAt
});
});
```
div
div
4
strong
Initialize SDK and Mount Payment Form
div
```html
```
**What Merchants Should Already Have:**
- Existing checkout form with amount and billing fields (name, address, etc)
- Form submission handler
- Payment method buttons (card, ACH, Apple Pay)
- ACH account type selector (checking/savings)
**What Merchants Need to Add:**
1. NPS SDK script tag in ``
2. Pass amount and billing fields (name, address, etc)
3. Pass ACH account type
4. Handle payment method switching
5. Container div `` where SDK iframe mounts
6. Styling
7. Backend endpoint (created in Step 3)
8. Initialize NPS SDK code
9. Update form submission to call `nps.tokenize()`
**Key Features:**
- **Multiple Payment Methods**: Card, ACH, Apple Pay with selection
- **Payment Method Switching**: SDK updates iframe content when user selects different method
- **ACH Account Type**: Checking/Savings selection on parent page, passed to iframe
- **Apple Pay Handling**: Pay Now button disabled when Apple Pay selected (Apple Pay has own button)
- **Full Styling Control**: Theme, colors, fonts, spacing all customizable
- **Amount Collection**: Amount field on parent page, passed during tokenization
- **Name Handling**: Full name combined for cardholderName
- **Metadata**: Anything else related to payment passed in metadata object in a systematic/similar way
div
div
5
strong
Process Payment Token
div
After tokenization succeeds, send the payment token to your backend:
```javascript
function handleTokenization(result) {
// Send token to your backend
fetch(, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
token: result.token,
// ... other payment details
})
});
}
```
## Configuration Options
div
Configure the SDK with various options to customize behavior and appearance.
### SDK Constructor Options
table
tr
th
Option
th
Type
th
Required
th
Description
tr
td
code
sessionToken
td
string
td
Yes
td
sessionToken from backend
tr
td
code
onReady
td
function
td
No
td
Callback when SDK is initialized
tr
td
code
onTokenizationComplete
td
function
td
No
td
Callback when tokenization succeeds
tr
td
code
onError
td
function
td
No
td
Callback for error handling
### Mount Options
div
```javascript
nps.mount('#payment-form', {
paymentMethod: 'card',
displayOptions: {
showLabels: true,
showIcons: true,
showErrors: true
},
styling: {
theme: 'light',
labelStyle: 'stacked',
fieldStyle: 'outlined',
fontFamily: 'Inter, sans-serif',
fontSize: '16px',
colors: {
primary: '#3B82F6',
error: '#DC2626',
success: '#10B981'
}
}
});
```
**Important:** The `styling` options are applied to the **iframe / iframe content** (payment fields), not the container element. You would need to add your CSS styling to the `#payment-form` container but make sure to test it thoroughly .
## Styling Customization
div
Refer the styling guide documentation
The following styling options customize the **iframe payment form fields**:
```javascript
const styling = {
theme: 'light', // 'light' or 'dark'
labelStyle: 'stacked', // 'stacked' or 'inline' or 'inline-split'
fieldStyle: 'outlined', // 'outlined' or 'filled' or 'underlined'
fontFamily: 'Inter, system-ui, sans-serif',...
fontSize: '16px',
colors: {
label: '#374151',
border: '#D1D5DB',
text: '#111827',
background: '#FFFFFF',
focusBorder: '#3B82F6',
error: '#DC2626',
errorBackground: '#FEF2F2',
success: '#10B981',
helpText: '#6B7280'
},
spacing: {
baseUnit: 8,
fieldHeight: 48,
fieldPadding: 12
},
borderRadius: 6,
borderWidth: 1
};
// Apply styling to iframe content
nps.mount('#payment-form', { styling });
```
### Container Styling
div
Apply CSS as needed:
```css
/* iFrame Container */
.payment-iframe-container {
margin-top: 10px;
min-height: 280px;
height: auto;
background: #e8ebee;
border-radius: 8px;
padding: 20px;
border: 1px solid #e5e7eb;
overflow: visible;
}
/* Compact container for Apple Pay - fits tightly around button */
.payment-iframe-container.applepay-active {
min-height: 80px !important;
height: 80px !important;
padding: 4px !important;
margin-top: 22px !important;
display: flex;
background: transparent !important;
border: none !important;
}
```
## Payment Methods
table
tr
td
div
h4
Credit/Debit Card
```javascript
nps.mount('#payment-form', {
paymentMethod: 'card',
cardOptions: {
supportedBrands: ['visa', 'mastercard', 'amex', 'discover'],
requireCvv: true,
showCardIcon: true
}
});
```
td
div
h4
ACH Bank Transfer
```javascript
nps.mount('#payment-form', {
paymentMethod: 'ach'
});
```
td
div
h4
Apple Pay
```javascript
// Check if Apple Pay is available
if (nps.isApplePayAvailable()) {
nps.mount('#payment-form', {
paymentMethod: 'applepay',
});
}
```
## Features
### Update Payment Method
div
Switch between payment methods without remounting:
```javascript
// Switch to ACH
await nps.updatePaymentMethod('ach');
// Switch back to card
await nps.updatePaymentMethod('card');
```
### Tokenization
div
When tokenizing, you must pass the amount , cardholder name and billing address. The **iframe only collects card, bank details**, while **name, amount and billing address are passed during tokenization**:
```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: {
}
});
// Response includes the payment token
console.log(result.token); // Payment token to send to backend
```
**For example-Important:**
- The iframe (mounted form) collects: **card number, expiration date, CVV**
- You collect separately: **amount, cardholder name, billing address**
- All are combined during `tokenize()` call
### Destroy SDK Instance
div
Clean up when done:
```javascript
// Remove iframe and clean up resources
nps.destroy();
```
## Error Handling
div
### Error Types
```javascript
function handleError(error) {
switch (error.code) {
case 'VALIDATION_ERROR':
// Invalid input in payment fields
console.error('Validation failed:', error.fields);
break;
case 'SESSION_EXPIRED':
// Session token has expired
console.error('Session expired, please refresh');
break;
case 'NETWORK_ERROR':
// Network connectivity issue
console.error('Network error, please try again');
break;
case 'TOKENIZATION_FAILED':
// Tokenization request failed
console.error('Failed to tokenize:', error.message);
break;
default:
console.error('Unknown error:', error);
}
}
```
## Migration from Legacy SDK
div
If migrating from an older NPS SDK version:
div
div
span
1.
strong
Update script URL
to new version
div
span
2.
strong
Update constructor syntax
(now uses single config object)
div
span
3.
strong
Update event handlers
to new callback names
div
span
4.
strong
Test thoroughly
before production deployment
## Support Resources
div
div
div
h3
Need Help?
div
div
Technical Support
a
NPSTechSupport@nelnet.net