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>
<script>
const style = {
showInputsLabel: true
};
document.addEventListener('DOMContentLoaded', () => {
const waitForNI = setInterval(() => {
if (window.NI && typeof window.NI.mountCardInput === 'function') {
clearInterval(waitForNI);
window.NI.mountCardInput('mount-id', {
apiKey: 'YOUR_API_KEY',
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 }) => {
console.log('Selected method:', selectedPaymentType, selectedDigitalPayment);
},
onChangeValidStatus: (status) => {
console.log('Validation:', status);
}
});
}
}, 100);
});
</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 |
Additional Setup for Apple Pay
To enable Apple Pay in Safari, the following steps are required:
-
Backend Code Changes
Ensure your backend is integrated to create payment orders/sessions with the correct details.
See Web SDK API Reference for required parameters. -
Merchant Domain Whitelisting
Your merchant domain must be whitelisted under your Apple Pay Merchant Identifier in the Apple Developer portal. -
Domain Verification
Complete Apple’s domain ownership verification by hosting the verification file on your domain:
.well-known/apple-developer-merchantid-domain-associationRefer to Apple’s Domain Verification Guide.
⚠️ Without these steps, Apple Pay will not appear in Safari even if the SDK integration is implemented correctly.
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'sdisplayis set toblockto 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