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
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'sdisplay
is set toblock
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