# Embedded Tokenization Experience

The **Embedded Tokenization Experience** 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 Embedded Tokenization Experience Is (and Is Not)

div
strong
Key idea:
br

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

### The SDK **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 SDK **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 payment experience supports:

- **Credit cards** — secure input fields rendered in the payment form
- **ACH** — secure input fields rendered in the payment form
- **Apple Pay** — Apple Pay button rendered directly on the merchant page via the SDK
- **PayPal and Venmo** — provider buttons rendered directly on the merchant page


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.

Refer [Creating Session Token Using JWT](/docs/session-token)

### 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 SDK
li
Payer enters payment details or authorizes via wallet
li
Merchant explicitly triggers tokenization
li
SDK returns an NPS token and metadata
## Tokenization Control

Tokenization is always merchant-initiated for card and ach.

- For **card, ACH**, the merchant explicitly calls `tokenize()` with the transaction details


In all cases, the merchant decides which payment methods to present, when to render them, and how to handle the result.

## Initializing the SDK (Example)

The following example demonstrates how a merchant might initialize the hosted payment experience.

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



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

<script>
  const up = new Widget({
 

    onReady: () => {
    },

    onTokenizationComplete: (result) => {
      // Send token to your backend
    },

    onError: (error) => {
    
    }
  });

  up.mount('#payment-container', {
    paymentType: 'card'
  });
</script>
```

## Tokenization Call

Once the SDK is ready, tokenization is triggered explicitly.


```js
up.tokenize({
  amount: 123.45,
  name: 'Jane Smith',
  billingAddress: {
    addressLine1: '123 Main St',
    addressLine2: 'Suite 100',
    city: 'Omaha',
    state: 'NE',
    postalCode: '68102',
    country: 'US'
  }
});
```

### Required by NPS

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


### 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 SDK returns:

- The **NPS token**
- Metadata that may include:
  - Card category, network, and last four digits
  - Issuing country and international status
  - Token group name
  - Surcharge calculations (if configured)


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

## Wallet-Based Payment Methods

For Apple Pay, PayPal, and Venmo:

- The SDK renders the appropriate wallet button
- Wallet authorization occurs through the provider's flow
- 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 payment form


If enabled:

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


## Styling & Layout

### SDK Styling

- Styling configuration affects **only the payment form contents**
- Input fields, labels, and buttons can be themed via the SDK
- See the [Styling section of the UI SDK Reference](/docs/ui-sdk-reference#styling) for all options


### Merchant-Owned Layout

- Container placement
- Page layout
- Fonts and surrounding UI


The payment form automatically sizes to its contents.

## Relationship to Payment Processing

The hosted payment experience **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 SDK to submit payments
- Handling raw payment data outside the SDK


## Summary

- The Embedded Tokenization Experience is required for cards and wallets
- Tokenization is always merchant-initiated for card and ach
- JWTs authenticate servers; session tokens authenticate browsers
- The SDK collects sensitive data and returns tokens
- Merchants retain full control of checkout flow and UX
- Tokens can be used immediately for payment processing