Web SDK Integration Guide

By leveraging our secure infrastructure, you'll eliminate the complexities of PCI DSS compliance, allowing you to focus on enhancing the user experience and accelerating your checkout process. Let's get started.

Overview

The Web SDK enables merchants to accept card payments securely while reducing their PCI DSS scope. Sensitive fields are hosted and served from N-Genius’ PCI-compliant environment.

You control the layout and styling of your form, while we handle the secure data collection and tokenization.

Prerequisites

Your API Key and Outlet Reference (from the N-Genius Portal)
A basic HTML page
Familiarity with JavaScript

1. Load the SDK

Include the SDK in the <head> or just before your closing </body> tag:

<script src="https://paypage.sandbox.ksa.ngenius-payments.com/hosted-sessions/sdk.js"></script>

2. Add the Mount Point

Create a placeholder in your HTML where the card input form will be injected:

<div id="mount-id"></div>

3. Mount the Card Input Form

Call the mountCardInput() method from the SDK with your configuration options:

const style = {
  showInputsLabel: true, // Optional: show labels above input fields
};

window.NI.mountCardInput('mount-id', {
  apiKey: 'HOSTED_SESSION_API_KEY', // 🔁 Corrected from hostedSessionApiKey
  outletRef: 'YOUR_OUTLET_REFERENCE',
  language: 'en',
  style,
  onSuccess: () => {
    console.log('Mount successful ✅');
  },
  onFail: (error) => {
    console.error('Mount failed ❌', error);
  },
  onChangeValidStatus: ({
    isCVVValid,
    isExpiryValid,
    isNameValid,
    isPanValid,
  }) => {
    console.log('Validation status:', {
      isCVVValid,
      isExpiryValid,
      isNameValid,
      isPanValid,
    });
  }
});

Field Styling

You can customize styles using the style object with the following keys:

const style = {
  main: {},      // Styles for the outer container
  base: {},      // Default input styles
  input: {},     // Custom input field styling
  invalid: {},   // Styling for invalid input states
  showInputsLabel: true, // Optional: show input labels above fields
};

Best Practices

Always test in sandbox before going live
Keep your API credentials secure
Use onChangeValidStatus to monitor input field status for better user feedback

Testing Tips

Use a test card from the sandbox test data to validate integration.

Need Help?

If you run into issues:

Visit N-Genius Portal
Contact your Relationship Manager or Onboarding Team.

Want to dive deeper?

For wallet support, tokenization, or custom validation flows, visit our full Hosted Session SDK Guide.