📖 Hosted Fields SDK
Secure SDK for embedding payment input fields (card number, expiry date, CVV, etc.) inside iframes. It is designed to ensure PCI‑compliance by isolating sensitive data from the merchant’s site.
🛠 Usage
-
Include the SDK on your checkout page (currently available via CDN only):
<script src="https://your-cdn.com/hf/sdk/lib/umd/index.js"></script> -
Initialize the SDK with your payment_id:
const sdk = HostedFieldsSDK({ paymentId: 'payment_id_required' }); -
To be able to mount the card fields on your page you need to prepare containers for that matter.
<form class="flex gap-4 flex-col" autocomplete="on"> <div id="cardNumber" class="w-full"></div> // card number field container <div class="flex gap-4 w-full"> <div id="expiryDate" class="w-full"></div> // expiry date field container <div id="cvv" class="w-full"></div> // card security code (cvv) field container </div> <div id="cardholderName" class="w-full"></div> // cardholder name field container <button type="button" class="submit-button" onclick="submitPayment()">Submit</button> </form> -
Mount the payment fields on you page:
sdk.onReady(() => { sdk.mountField('#cardNumber', { fieldType: 'cardNumber', label: 'Card number', fieldStyles: { variant: 'outlined' } }); sdk.mountField('#expiryDate', { fieldType: 'expiryDate', label: 'Expiry date' }); sdk.mountField('#cvv', { fieldType: 'cvv', label: 'Card security code' }); sdk.mountField('#cardholderName', { fieldType: 'cardholderName', label: 'Cardholder name' }); }); sdk.onError((err) => console.error('SDK Error:', err)); -
Start the SDK:
sdk.init(); -
Tokenize on form submission:
async function submitPayment(e) { e?.preventDefault(); try { const result = await sdk.handleSubmit(); console.log(result); if(result?.redirectUrl) window.location.replace(result.redirectUrl); document.getElementById('output').textContent = JSON.stringify(result, null, 2); } catch (error) { console.error('--',error); } }
🔑 Available Methods
-
new HostedFieldsSDK(config)
Creates a new SDK instance.
Parameters:- payment_id (string, required) --
paymentIdyou received after creating the payment. - Payment method must be
paymentMethod: BASIC_CARD, - payment state
state: CHECKOUT - and transaction must have valid amount
amount: 10.
- payment_id (string, required) --
-
.init()
Initializes the SDK and validates your payment id. Must be called before mounting fields.
-
.onError(callback)
Registers a callback to handle initialization or runtime errors.
- Callback receives: an error object with a message.
-
.mountField(containerSelector, options)
Injects a secure payment input field (inside an iframe) into the specified container on your page.
Parameters:-
containerSelector (string, required) - CSS selector for a container
divin your HTML. -
options (object, required):
-
fieldType- the type of payment field to render. Available:
- cardNumber
- expiryDate
- cvv
- cardholderName
- label (string, optional) — the label text displayed above the input.
-
fieldStyles (object, optional) — customize appearance:
- variant —
standardoroutlined - fieldWrapper — custom CSS styles for the field wrapper
- inputBase — custom CSS styles for the input
- invalidInputBase — styles applied when the input is invalid
- labelBase — custom CSS styles for the label
- invalidLabelBase — styles applied when input is invalid
- variant —
-
fieldType- the type of payment field to render. Available:
-
containerSelector (string, required) - CSS selector for a container
🖼 Full example form:
<div class="flex flex-col w-sm border rounded mx-auto mt-6">
<div class="flex items-center p-4">
<h3>Basic card form</h3>
</div>
<form class="flex gap-4 flex-col" autocomplete="on">
<div id="cardNumber" class="w-full"></div>
<div class="flex gap-4 w-full">
<div id="expiryDate" class="w-full"></div>
<div id="cvv" class="w-full"></div>
</div>
<div id="cardholderName" class="w-full"></div>
<button type="button" class="submit-button" onclick="submitPayment()">Submit</button>
</form>
</div>
<!--Load script with hosted fields-->
<script src="https://your-domain.com/hf/sdk/lib/umd/index.js"></script>
<script>
<!-- payment id required -->
const sdk = HostedFieldsSDK({ paymentId: <payment_id> });
sdk.onReady(() => {
sdk.mountField('#cardNumber', {
fieldType: 'cardNumber',
label: 'Card Number',
iframeStyle: 'width: 100%; border: none;',
fieldStyles: {
fieldWrapperBase: {
paddingTop: '0.375rem',
position: 'relative',
width: '100%',
display: 'flex',
flexDirection: 'column',
},
inputBase: {
margin: '0.125rem',
marginTop: '0',
border: '1px solid #2E84F2',
borderRadius: '0.75rem',
padding: '0.75rem 1rem',
':hover': {
border: '1px solid orange',
},
':focus': {
outline: 'none',
border: '1px solid green',
}
},
labelBase: {
fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
position: 'absolute',
top: '0',
left: '1rem',
fontSize: '0.75rem',
backgroundColor: 'white',
zIndex: 1,
padding: '0 0.125rem',
},
invalidInputBase: {
border: '1px solid red',
},
invalidLabelBase: {
color: 'red',
}
},
});
sdk.mountField('#expiryDate', {
fieldType: 'expiryDate',
label: 'Expiry Date',
fieldStyles: {
variant: 'outlined',
labelBase: {
fontSize: '0.75rem',
color: '#512ccc',
}
},
});
sdk.mountField('#cvv', {
fieldType: 'cvv',
label: 'Card Security Code',
fieldStyles: {
variant: 'standard',
}
});
sdk.mountField('#cardholderName', {
fieldType: 'cardholderName',
label: 'Cardholder Name',
fieldStyles: {
variant: 'outlined',
}
});
});
sdk.onError((err) => console.error("SDK Error:", err));
sdk.init();
async function submitPayment(e) {
e?.preventDefault();
try {
const result = await sdk.handleSubmit();
console.log(result);
if(result?.redirectUrl) window.location.replace(result.redirectUrl);
document.getElementById('output').textContent = JSON.stringify(result, null, 2);
} catch (error) {
console.error('SDK error on submit:',error);
}
}
</script>