Skip to content
/
Hosted Tokenization Ifram...
Last updated

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)

Key idea:
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

Key idea:
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

  1. Backend creates JWT
  2. Backend creates session token
  3. Browser initializes the iframe via the SDK
  4. Payer enters payment details inside the iframe
  5. Merchant explicitly calls tokenize()
  6. Iframe returns an NPS token and metadata

Explicit Tokenization

Tokenization is always explicit.

Important:
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.

<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.

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
Previous page
Next page