@nmipayments/nmi-pay

NMI Embedded Component for Payments - Svelte-based Implementation

Overview

This package provides Svelte-based payment widgets that can be embedded into any JavaScript application. It includes both standard payment processing and 3D Secure authentication widgets, with support for multiple payment methods including Apple Pay and Google Pay.

Features

• 🎯 Multiple Payment Methods: Card, ACH, Apple Pay, Google Pay
• 🔒 3D Secure Support: Built-in 3D Secure authentication widget
• 💳 Express Checkout: Quick checkout with Apple Pay and Google Pay
• 🎨 Customizable Appearance: Flexible theming and styling options
• 📱 Responsive Design: Works seamlessly across desktop and mobile
• ⚡ Framework Agnostic: Can be used in any JavaScript framework
• 🔧 TypeScript Support: Full TypeScript definitions included

Installation

npm install @nmipayments/nmi-pay

Required CSP Directives

Content-Security-Policy: 
  frame-src 'self' https://secure.nmi.com https://secure.networkmerchants.com;
  connect-src 'self' https://secure.nmi.com https://secure.networkmerchants.com;

Usage

Standard Payment Widget

import { mountNmiPayments } from '@nmipayments/nmi-pay';

const widget = mountNmiPayments('#payment-container', {
  tokenizationKey: 'your-tokenization-key',
  layout: 'multiLine',
  paymentMethods: ['card', 'ach', 'apple-pay', 'google-pay'],
  appearance: {
    theme: 'light',
    layoutSpacing: 'default',
    textSize: 'default',
    radiusSize: 'default'
  },
  expressCheckoutConfig: {
    applePay: {
      merchantId: 'your-apple-merchant-id',
      displayName: 'Your Business'
    },
    googlePay: {
      merchantId: 'your-google-merchant-id',
      environment: 'TEST' // or 'PRODUCTION'
    }
  },
  onPay: async (token) => {
    // Handle payment processing
    console.log('Payment token:', token);
    // Return true for success or error message for failure
    return true;
  },
  onChange: (state) => {
    console.log('Payment state changed:', state);
  },
  onFieldsAvailable: () => {
    console.log('Payment fields are ready');
  }
});

// Clean up when done
widget.destroy();

3D Secure Widget

import { mountNmiThreeDSecure } from '@nmipayments/nmi-pay';

const threeDSWidget = mountNmiThreeDSecure('#threeds-container', {
  tokenizationKey: 'your-tokenization-key',
  paymentInformation: {
    amount: '10.00',
    currency: 'USD',
    // ... other payment details
  },
  onAuthenticated: (result) => {
    console.log('3D Secure authentication completed:', result);
  },
  onError: (error) => {
    console.error('3D Secure error:', error);
  }
});

Direct Custom Element Usage

<!-- Payment Widget -->
<nmi-pay-widget
  id="payment-widget"
  tokenization-key="your-tokenization-key"
  layout="multiLine"
  payment-methods='["card", "ach", "apple-pay", "google-pay"]'>
</nmi-pay-widget>

<!-- 3D Secure Widget -->
<nmi-threeds-widget
  id="threeds-widget"
  tokenization-key="your-tokenization-key">
</nmi-threeds-widget>

<script>
  const paymentWidget = document.getElementById('payment-widget');
  const threeDSWidget = document.getElementById('threeds-widget');
  
  // Configure callbacks
  paymentWidget.onPay = async (token) => {
    console.log('Payment completed:', token);
    return true;
  };
  
  threeDSWidget.onAuthenticated = (result) => {
    console.log('3D Secure completed:', result);
  };
</script>

React Integration

For React applications, use the dedicated React wrapper:

npm install @nmipayments/nmi-pay-react

import { NmiPayments, NmiThreeDSecure } from '@nmipayments/nmi-pay-react';

function PaymentForm() {
  return (
    <>
      <NmiPayments
        tokenizationKey="your-tokenization-key"
        layout="multiLine"
        paymentMethods={['card', 'ach', 'apple-pay', 'google-pay']}
        onPay={async (token) => {
          console.log('Payment completed:', token);
          return true;
        }}
      />
      
      <NmiThreeDSecure
        tokenizationKey="your-tokenization-key"
        paymentInformation={{
          amount: '10.00',
          currency: 'USD'
        }}
        onAuthenticated={(result) => {
          console.log('3D Secure completed:', result);
        }}
      />
    </>
  );
}

API Reference

mountNmiPayments(targetElement, options)

Mounts an NMI payment widget to a target element.

Parameters:

• targetElement (HTMLElement | string): DOM element or CSS selector
• options (PaymentWidgetProps): Payment widget configuration

Returns: MountedNmiPayments object with methods:

• element: Reference to the mounted widget element
• destroy(): Removes the widget and cleans up

PaymentWidgetProps

| Property | Type | Default | Description | |----------|------|---------|-------------| | tokenizationKey | string | - | Required. Your NMI tokenization key | | layout | 'singleLine' \| 'multiLine' \| 'stacked' | 'multiLine' | Layout style for the payment form | | paymentMethods | Array<'card' \| 'ach' \| 'apple-pay' \| 'google-pay'> | ['card', 'ach'] | Available payment methods | | paymentMethodLayout | 'singleLine' \| 'stacked' | 'singleLine' | Layout for payment method selector | | appearance | Appearance | {} | Styling configuration | | expressCheckoutConfig | ExpressCheckoutConfig | {} | Apple Pay and Google Pay configuration | | showDivider | boolean | false | Whether to show dividers between sections | | payButtonText | string | 'Pay' | Text for the pay button | | onPay | (token: string) => Promise<true \| string> | - | Required. Payment handler function | | onChange | (state: PaymentState) => void | - | Called when payment state changes | | onFieldsAvailable | () => void | - | Called when payment fields are ready |

mountNmiThreeDSecure(targetElement, options)

Mounts an NMI 3D Secure widget to a target element.

Parameters:

• targetElement (HTMLElement | string): DOM element or CSS selector
• options (NmiThreeDSecureProps): 3D Secure widget configuration

Returns: MountedNmiThreeDSecure object with methods:

• element: Reference to the mounted widget element
• destroy(): Removes the widget and cleans up

NmiThreeDSecureProps

| Property | Type | Default | Description | |----------|------|---------|-------------| | tokenizationKey | string | - | Required. Your NMI tokenization key | | paymentInformation | PaymentInformation | - | Required. Payment details for authentication | | onAuthenticated | (result: any) => void | - | Called when authentication completes | | onError | (error: string) => void | - | Called when authentication fails |

Express Checkout Configuration

interface ExpressCheckoutConfig {
  applePay?: {
    merchantId: string;
    displayName: string;
    countryCode?: string;
    currencyCode?: string;
  };
  googlePay?: {
    merchantId: string;
    environment: 'TEST' | 'PRODUCTION';
    countryCode?: string;
    currencyCode?: string;
  };
}

Appearance Configuration

interface Appearance {
  theme?: 'light' | 'dark';
  layoutSpacing?: 'compact' | 'default' | 'spacious';
  textSize?: 'small' | 'default' | 'large';
  radiusSize?: 'none' | 'small' | 'default' | 'large';
  primaryColor?: string;
  backgroundColor?: string;
  borderColor?: string;
  textColor?: string;
}

Events and Callbacks

Payment Widget Events

• onPay: Called when payment is submitted (must return true for success or error message for failure)
• onChange: Called when payment state changes (field validation, method selection, etc.)
• onFieldsAvailable: Called when payment fields are ready for interaction

3D Secure Widget Events

• onAuthenticated: Called when 3D Secure authentication completes successfully
• onError: Called when 3D Secure authentication fails or encounters an error

Bundle Information

The package provides multiple build formats:

• ES Module: dist/index.js (main entry point)
• CommonJS: dist/index.cjs (for Node.js compatibility)
• IIFE: dist/nmi-payments-cdn.iife.js (for direct browser usage)
• Widgets: Individual widget files for direct script inclusion
  • dist/nmi-pay-widget.js
  • dist/nmi-3ds.js

Architecture

Built with modern web technologies:

• Svelte 5: Core component framework for optimal performance
• TypeScript: Full type safety and developer experience
• Vite: Fast build system and development server
• Web Components: Standards-based custom elements for framework interoperability

The package creates custom elements that can be used in any framework while maintaining the performance benefits of Svelte's compiled output.

Browser Support

• Modern browsers with ES2020 support
• Safari 14+
• Chrome 84+
• Firefox 90+
• Edge 84+

License

MIT