How to set up the hosted session SDK to support wallets

📘
Before you begin: This guide assumes you've already integrated the Web SDK component. If not, refer to the Web SDK Integration Guide.

Step 1: Load the SDK and Mount the Card Input

Include the SDK in your HTML and use the mountCardInput() method to initialize the form.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Hosted Session with Wallets</title>
  <script src="https://paypage.sandbox.ksa.ngenius-payments.com/hosted-sessions/sdk.js"></script>
</head>
<body>
  <div id="mount-id"></div>
  <div id="wallet_iframe"></div>

  <script>
    const style = {
      showInputsLabel: true
    };

    window.NI.mountCardInput('mount-id', {
      apiKey: 'HOSTED_SESSION_API_KEY', // Previously hostedSessionApiKey
      outletRef: 'YOUR_OUTLET_REF',
      language: 'en',
      style,
      multiplePaymentMethods: true,
      orderDetails: {
        amount: 100,
        currency: 'SAR',
        formattedAmount: '1.00'
      },
      onSuccess: () => console.log('Form mounted successfully ✅'),
      onFail: () => console.error('Failed to mount form ❌'),
      onChangePaymentMethod: ({ selectedPaymentType, selectedDigitalPayment }) => {
        if (selectedPaymentType === 'DIGITAL_PAYMENTS' && selectedDigitalPayment) {
          enableMakePaymentButton();
        }
      },
      onChangeValidStatus: ({
        isCVVValid,
        isExpiryValid,
        isNameValid,
        isPanValid
      }) => {
        console.log('Validation:', {
          isCVVValid,
          isExpiryValid,
          isNameValid,
          isPanValid
        });
      }
    });
  </script>
</body>
</html>

Parameter Overview

Parameter	Required	Description
`apiKey`	✅	Your Hosted Session API key (from portal)
`outletRef`	✅	Outlet reference (from portal)
`language`	✅	UI language (`en` or `ar`)
`style`	✅	Object defining visual styles
`multiplePaymentMethods`	✅	Enables digital wallets tab
`orderDetails`	✅*	Required if `multiplePaymentMethods` is `true`
`onChangePaymentMethod`	✅	Callback when wallet or card tab is switched
`onChangeValidStatus`	✅	Callback for field-level validation

📘
You can only use Apple Pay on Safari.

Step 2: Supporting Samsung Pay

Samsung Pay requires an additional session flow via generateSessionId().

HTML Setup

<div id="wallet_modal" style="display: none;">
  <div id="wallet_iframe"></div>
</div>

JavaScript Example

async function createSession() {
  try {
    const response = await window.NI.generateSessionId({
      mountId: 'wallet_iframe',
      containerId: 'wallet_modal' // Optional, used to make hidden modal visible
    });

    const sessionId = response.session_id;
    console.log('Session ID:', sessionId);
  } catch (err) {
    console.error('Failed to create session:', err);
  }
}

Parameters for generateSessionId():

mountId (required): ID of the element where the Samsung Pay iframe will render.
containerId (optional): If passed, this element's display is set to block to reveal the modal.

Need Help?

If you're unsure how to enable wallet support or retrieve credentials:

Visit your N-Genius Portal
Reach out to your Relationship Manager or onboarding team