# Hosted Tokenization Iframe

The **Hosted Tokenization Iframe** is the only supported mechanism for securely collecting sensitive payment information in Nelnet Payment Services (NPS).

It allows merchants and partners to collect payment details in the browser **without those details ever touching their systems**, and returns a reusable NPS token that can be used for payment processing, reporting, and lifecycle management.

## What the Hosted Tokenization Iframe Is (and Is Not)

div
strong
Key idea:
br

  The iframe collects sensitive data. Your application controls the checkout experience.

### The iframe **does**

- Securely collect sensitive payment credentials
- Embed required third-party SDKs (Apple Pay, PayPal, Venmo)
- Perform tokenization, fraud analysis, and CAPTCHA challenges
- Return an NPS token and token metadata to the browser


### The iframe **does not**

- Submit payments
- Own your checkout UI
- Control navigation, buttons, or page layout
- Call your backend APIs


Merchants remain fully in control of their user experience.

## Supported Payment Methods

The hosted tokenization iframe supports:

- **Credit cards**
- **ACH**
- **Apple Pay**
- **PayPal and Venmo**


All payment methods follow the same outcome:

> A successful flow returns an **NPS token** to the browser.


## Authentication & Session Model

div
strong
Key idea:
br

  JWTs authenticate servers. Session tokens authenticate the browser.

### Required by NPS

1. Your backend creates a **JWT** using API keys
2. Your backend exchanges the JWT for a **session token**
3. The browser initializes a payment session using the session token


### Provided as Examples

- How you transport the session token to the browser
- How you structure your checkout page
- How you send token data back to your backend


## High-Level Flow

div
ol
li
Backend creates JWT
li
Backend creates session token
li
Browser initializes the iframe via the SDK
li
Payer enters payment details inside the iframe
li
Merchant explicitly calls 
code
tokenize()
li
Iframe returns an NPS token and metadata
## Explicit Tokenization

Tokenization is **always explicit**.

div
strong
Important:
br

  The iframe never auto-tokenizes. Your application must explicitly request tokenization.

This ensures merchants control:

- When tokenization occurs
- Which amount, name, and address context is provided
- How retries and errors are handled


## Initializing the Iframe (Example)

The following example demonstrates how a merchant might initialize the hosted tokenization iframe.

> This example focuses only on iframe responsibilities.
Checkout layout, buttons, and page flow are owned by the merchant.



```html
<div id="nps-container"></div>

<script>
  const nps = new NPS({
    sessionId: '<SESSION_ID>',
    sessionToken: '<SESSION_TOKEN>',
    containerId: 'nps-container',

    onReady: () => {
      console.log('Tokenization iframe ready');
    },

    onTokenizationComplete: (result) => {
      // Send token and metadata to your backend
      console.log(result);
    },

    onError: (error) => {
      console.error(error);
    }
  });
</script>
```

## Tokenization Call

Once the iframe is ready, tokenization is triggered explicitly.


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

### Required by NPS

- `amount`
- Payer name and billing address (for cards)


### Merchant-Defined

- When tokenization is triggered
- How validation and retries are handled
- How results are routed to backend systems


## Returned Token & Metadata

On success, the iframe returns:

- The **NPS token**
- Metadata that may include:
  - Token type (PAN, network token, wallet token)
  - Token last four digits
  - BIN information
  - Surcharge calculations (if configured)
  - Risk identifiers


This data is safe to handle in the browser and may be forwarded to your backend.

## Wallet-Based Payment Methods

For Apple Pay and PayPal / Venmo:

- The iframe renders the appropriate wallet button
- Wallet authorization occurs inside the iframe
- The same `onTokenizationComplete` callback is used
- The result is an NPS token, consistent with card and ACH flows


No special merchant-side handling is required beyond initiating tokenization.

## Fraud Controls & CAPTCHA

NPS applies fraud analytics during tokenization.

Depending on merchant configuration:

- Behavioral and device signals are evaluated
- A CAPTCHA challenge may be presented inside the iframe


If enabled:

- The payer must complete the challenge before tokenization completes
- The merchant does not need to integrate CAPTCHA logic


## Styling & Layout

### Iframe Styling

- Styling configuration affects **only iframe contents**
- Input fields, labels, and buttons inside the iframe can be themed


### Merchant-Owned Layout

- Container placement
- Page layout
- Fonts and surrounding UI


The iframe automatically sizes to its contents.

## Relationship to Payment Processing

The hosted tokenization iframe **does not process payments**.

After tokenization:

1. The browser sends the token to your backend
2. Your backend submits a payment using the Payments API
3. Tokens participate in reporting and lifecycle management automatically


## Common Integration Mistakes

- Attempting to tokenize without calling tokenize()
- Using session tokens for backend API calls
- Expecting the iframe to submit payments
- Handling raw payment data outside the iframe


## Summary

- The hosted tokenization iframe is required for cards and wallets
- Tokenization is always explicit
- JWTs authenticate servers; session tokens authenticate browsers
- The iframe collects sensitive data and returns tokens
- Merchants retain full control of checkout flow and UX
- Tokens can be used immediately for payment processing