UI SDK Reference

Complete API reference for the Widget SDK. This document describes every constructor option, method, callback, styling property, and error code available in the SDK.

For step-by-step integration guides, see Card & ACH, Apple Pay, and PayPal & Venmo.

Creates a new SDK instance and establishes a session. onTokenizationComplete is required. Everything else is optional and depends on which payment methods you plan to use.

Creating Session Token Using JWT

For Apple Pay, the merchant identifier is passed in the applePay mount options (not the constructor), and the domain is detected automatically from the page — see applePay Sub-Options.

Callbacks

const wg = new Widget({
  tokenGroup: '<TOKEN_GROUP>',
  entityId: '<ENTITY_ID>',
  onReady: () => {},
  onTokenizationComplete: (result) => {},
  onError: (error) => {},
  onCancel: (payload) => {}
});

Renders the payment UI inside the specified container element.

• For card and ACH, this renders a secure hosted payment form inside an iframe.
• For paypal, venmo, or paypalVenmo, this loads the PayPal SDK and renders checkout button(s) directly in the container.
• For applePay, the SDK loads the Apple Pay JS SDK and renders the Apple Pay button directly in the container.

Styling and display options can be passed here to control the look and feel of the payment form. See Styling and Display Options for all available options.

These options apply to the direct card and ACH mounts only; they do not apply to PayPal, Venmo, Apple Pay, or the hosted Payment Widget modes. All are optional.

const wg = new Widget({
  onTokenizationComplete: (result) => { /* ... */ },
  onHelpClick: ({ field }) => showHelpModal(field),
  onFormReady: ({ ready }) => { payButton.disabled = !ready; }
});

wg.mount('#payment-form', {
  paymentMethod: 'card',
  supportedCardBrands: ['visa', 'mastercard'],
  helpIcons: ['securityCode'],
  locale: 'es'
});

Card / ACH Example:

wg.mount('#payment-container', {
  paymentMethod: 'card',
  styling: { ... },
  displayOptions: { ... }
});

PayPal Example:

wg.mount('#paypalVenmo-container', {
  paymentMethod: 'paypal',
  paypal: {
    returnUrl: 'https://example.com/success',
    cancelUrl: 'https://example.com/cancel'
  }
});

paypalVenmo Example (Renders Both PayPal And Venmo):

wg.mount('#paypalVenmo-container', {
  paymentMethod: 'paypalVenmo',
  paypal: {
    returnUrl: 'https://example.com/success',
    cancelUrl: 'https://example.com/cancel'
  }
});

Sets or refreshes the session token used by the SDK for all payment API calls. This method must be called before tokenize() (for card/ACH) or before the user clicks a PayPal, Venmo, or Apple Pay button. The token is stored internally and used for all subsequent API calls until updated again.

Call this method whenever you need to provide a fresh session token — for example, when the user selects a paypalVenmo payment method, or right before submitting a card/ACH payment.

const token = await fetchSessionToken();
wg.updateSessionToken(token);

Switches the active payment method without tearing down and remounting. This is useful when your checkout page lets the customer toggle between card, ACH, and paypalVenmo payment methods.

When switching between card/ACH and PayPal/Venmo/paypalVenmo, the SDK automatically handles cleanup and re-rendering.

wg.updatePaymentMethod('ach', { accountType: 'checking' });

wg.updatePaymentMethod('paypalVenmo');

Triggers tokenization for card and ACH payment methods only. When called, the SDK securely collects the payment data from the hosted form and exchanges it for an NPS token.

A session token must be set via updateSessionToken() before calling this method.

On success, onTokenizationComplete is invoked with the token and associated metadata. On failure, onError is invoked with a structured error payload. If the iframe does not respond within 30 seconds, the SDK automatically times out and emits an UNEXPECTED_ERROR.

Apple Pay, PayPal, and Venmo do not use this method. Those payment methods handle tokenization through their respective button clicks — the customer's interaction triggers the flow directly, and results are delivered via onTokenizationComplete.

const token = await fetchSessionToken();
wg.updateSessionToken(token);

const result = await wg.tokenize({
  amount: 125.00,
  accountHolderName: 'Jane Smith',
  billingAddress: {
    addressLine1: '123 Main St',
    addressLine2: 'Suite 100',     // optional
    city: 'Omaha',                 
    state: 'NE',                   
    postalCode: '68102',
    country: 'US'
  }
});

Apple Pay is rendered via mount() with paymentMethod: 'applePay' and an applePay options object. The SDK renders an Apple Pay button directly on the merchant page. When the customer clicks the button, the native Apple Pay payment sheet opens with the amount specified in applePay.total. After the customer authorizes, onTokenizationComplete is invoked with the token (result.paymentMethod is 'applePay'). There is no separate tokenize() call for Apple Pay.

The SDK automatically loads the Apple Pay JS SDK. On non-Safari browsers (Chrome, Edge, including Windows), the payment sheet is replaced by a code the customer scans with an iPhone (iOS 18+) to authorize the payment there.

The merchant must host the Apple domain verification file at /.well-known/apple-developer-merchantid-domain-association on their registered domain. The SDK always uses the hostname of the page for merchant validation, so the checkout page must be served from that verified domain — there is no domain option to configure.

A session token must be set via updateSessionToken() before the customer clicks the button. The country and currency are always US and USD. Supported card networks are Visa, Mastercard, American Express, and Discover.

The sum of the context amounts cannot exceed total.amount.

The SDK validates the required fields and rejects the request with an error if any are missing. The recurring payment plan (billing schedule, agreement, and any trial pricing) is managed by NPS, not Apple.

One-time payment:

wg.mount('#apple-pay-button', {
  paymentMethod: 'applePay',
  applePay: {
    total: { label: 'Nelnet Campus Commerce', amount: '75.00' },
    partnerInternalMerchantIdentifier: '<MERCHANT_IDENTIFIER>'
  }
});

Multi-merchant payment:

wg.mount('#apple-pay-button', {
  paymentMethod: 'applePay',
  applePay: {
    total: { label: 'Total Amount', amount: '110.00' },
    lineItems: [
      { label: 'AAA University', amount: '100.00' },
      { label: 'BBB Service Fee', amount: '10.00' }
    ],
    multiTokenContexts: [
      {
        partnerMerchantIdentifier: 'TESTCLIENT_a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6',
        entityId: 'A-123',
        entityName: 'AAA University',
        amount: '100.00'
      },
      {
        partnerMerchantIdentifier: 'TESTCLIENT_a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6',
        entityId: 'B-456',
        entityName: 'BBB Service Fee',
        amount: '10.00'
      }
    ]
  }
});

Recurring payment:

Set total.amount (the sheet total) to the recurring amount in regularBilling.

wg.mount('#apple-pay-button', {
  paymentMethod: 'applePay',
  applePay: {
    total: { label: 'Meal Plan Subscription', amount: '9.99' },
    partnerInternalMerchantIdentifier: '<MERCHANT_IDENTIFIER>',
    recurringPaymentRequest: {
      paymentDescription: 'Campus Meal Plan — billed monthly',
      regularBilling: {
        label: 'Meal Plan Subscription',
        amount: '9.99'
      },
      managementURL: 'https://checkout.example.com/account/subscriptions'
    }
  }
});

Moves keyboard focus to a field inside the secure payment form (card and ACH mounts only). Typically used together with onFieldErrors so an error-summary banner on your page can jump the payer to the field that needs attention.

wg.focusField('cardNumber');

Unmounts the payment form, removes event listeners, and releases all resources held by the SDK instance. Call this when the checkout page is being torn down or when the payment form is no longer needed.

wg.destroy();

Invoked when the payment form is fully initialized and ready to accept input. This is a good place to enable your "Pay" button or show the payment form container if it was hidden during loading.

Invoked after successful tokenization. This callback is used by all payment methods — card, ACH, Apple Pay, PayPal, and Venmo. The result contains the NPS token and metadata about the payment credential. The exact set of properties depends on the payment method. Some of them are given below.

Invoked when a validation, session, network, or provider error occurs. The error object always contains responseCode, responseMessage, and a description string.

onError: (error) => {
  console.error(`[${error.responseCode}] ${error.responseMessage}: ${error.description}`);
}

Invoked when the user cancels a PayPal, Venmo, or Apple Pay payment (e.g. closes the popup without completing). This callback is not fired for card or ACH — those flows have no cancel concept since the form is inline.

The payload follows the same structure as error payloads.

onCancel: (payload) => {
  console.log(payload.description); // "Payment cancelled by user"
}

Invoked when the payer clicks the ? help icon beside a field (rendered via the helpIcons mount option). The SDK renders no help content; displaying a modal or tooltip is your page's job.

Also dispatched as a window CustomEvent named wg-help-click with the same payload in event.detail.

onHelpClick: ({ field }) => {
  showHelpModal(field); // e.g. explain what a CVV is
}

Invoked when the aggregate validity of the card/ACH form changes: ready: true when every required field for the active payment method is complete and valid, ready: false if the form regresses (for example, the payer edits a field back to an invalid state). Informational only; it does not start tokenization. The typical use is enabling or disabling your Pay button.

Also dispatched as a window CustomEvent named wg-form-ready with the same payload in event.detail.

onFormReady: ({ ready }) => {
  document.getElementById('pay-btn').disabled = !ready;
}

Invoked when a tokenize() attempt is blocked by field validation. The payload lists every errored field with its localized message, which is useful for building an accessible error-summary banner on your page. Pair each entry with focusField(field) to jump the payer to the field. On a blocked tokenize the SDK also automatically scrolls the page to the first errored field; no wiring is needed for that.

Also dispatched as a window CustomEvent named wg-field-errors with the same payload in event.detail.

onFieldErrors: ({ errors }) => {
  renderErrorSummary(errors.map(e => ({
    text: e.message,
    onClick: () => wg.focusField(e.field)
  })));
}

Styling is passed via options.styling in the mount() call. All styling options affect the payment form only — the surrounding page layout, fonts, and design remain fully under merchant control.

These options control the overall visual structure of the payment form.

When fieldLayout is inline, labelStyle is automatically forced to hidden.

Color values are passed via styling.colors. These control the color scheme of input fields, labels, and error states inside the payment form.

These options control font choices and sizing for various elements inside the payment form.

These options control the physical sizing and spacing of input fields and the payment form.

wg.mount('#payment-container', {
  paymentMethod: 'card',
  styling: {
    theme: 'light',
    labelStyle: 'floating',
    fieldStyle: 'outlined',
    fieldLayout: 'stacked',
    fontFamily: 'Inter',
    fontSize: 15,
    labelFontSize: 14,
    labelFontWeight: 500,
    helpTextFontSize: 14,
    helpTextFontWeight: 400,
    spacing: 12,
    borderRadius: 4,
    borderWidth: 1,
    inputHeight: 36,
    iframeWidth: '100%',
    colors: {
      label: '#5A5E66',
      border: '#C4C8CC',
      error: '#D32F2F',
      text: '#000000',
      focusBorder: '#3B82F6',
      helpText: '#9CA3AF'
    }
  }
});

Display options are passed via options.displayOptions in the mount() call. They control the visibility of labels, icons, placeholders, and other UI elements inside the payment form.

wg.mount('#payment-container', {
  paymentMethod: 'card',
  displayOptions: {
    showLabels: true,
    showIcons: true,
    showErrors: true,
    showPlaceholders: true,
    showSecurityCodeIndicator: true
  }
});

All errors surfaced through onError or onCancel use a standardized payload format. The same codes are used consistently across all payment methods — the description field identifies the specific cause.

{
  "responseCode": "E400",
  "responseMessage": "SDK_ERROR",
  "description": "Human-readable detail about what went wrong"
}

• Card/ACH errors are returned both as promise rejections from tokenize() and via the onError callback.
• PayPal/Venmo and Apple Pay errors are delivered only via the onError callback (there is no promise to reject).
• onCancel is only fired for PayPal, Venmo, and Apple Pay. Card and ACH have no cancel concept.
• The description field always contains a human-readable message suitable for logging or display.

This table shows which fields are required in the tokenize() call for card and ACH. A session token must be set via updateSessionToken() before calling tokenize().

Apple Pay, PayPal, and Venmo do not use tokenize(). Their transaction details are passed directly in the mount() options (applePay or paypal), and the SDK handles the flow on button click. For PayPal, Venmo, and Apple Pay, call updateSessionToken() before the user clicks the payment button.