Developers
HomeMerchantsDevelopers

How to set up the hosted session SDK to support wallets

This guide explains how to enhance your Hosted Session SDK integration to support digital wallets such as Apple Pay, Google Pay, and Samsung Pay.

📘

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.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: 'AED',
        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


ParameterRequiredDescription
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: