Hosted Fields

Our Hosted Fields solution requires your checkout page to implement specific HTML/JavaScript elements:

<script id="hosted-fields-sdk" crossorigin="anonymous"></script>

<form id="payment-form" novalidate>
 <div id="cardholderName"></div>
	 <div id="cardNumber"></div>
	 <div id="expiryDate"></div>
	 <div id="csc"></div>
	 <div id="cardBrands"></div>
<button id="submit-button" type="submit" disabled>Pay</button>
</form>


<script>

// Store our platform’s response to the CreateHostedSession request
var apiResponse;

document.addEventListener(‘DOMContentLoaded’, () => {
 
	const sdkScript = document.getElementById(‘hosted-fields-sdk’);
	sdkScript.src = apiResponse.sdkUrl;
	sdkScript.integrity = ‘sha256-${apiResponse.sdkSri}’;
	sdkScript.onload = () => initializeHostedFields(apiResponse);
});

function initializeHostedFields(apiResponse) {
	const submitButton = document.getElementById('submit-button');
	const resultDisplay = document.getElementById('result-display');
	const config = {
		"sessionData": apiResponse.sessionData,
		"logLevel": "debug",
		"style": {
			"input": {
			"color": "#000000",
			"font-family": "courier, monospace",
			"font-size": "14px"
			},
			"input::placeholder": {
				"color": "#999999"
				}
			},
		"fields": {
			"cardNumber": {
				"id": "cardNumber",
				"title": "Your card number",
				"placeholder": "0000 0000 0000 0000"
			},
			"cardholderName": {
				"id": "cardholderName",
				"title": "Your name",
				"placeholder": "John"
			},
			"cardBrands": {
				"id": "cardBrands",
				"title": "Your card brand",
				"placeholder": "VISA"
			},
			"expiryDate": {
				"id": "expiryDate",
				"caption": "Your card expiration date",
				"checkExpiredDate": "true",
				"placeholder": "MM/YY"
			},
			"csc": {
				"id": "csc",
				"title": "Your card security code",
				"caption": "Your card security code",
				"placeholder": "123"
			}
		}
	}

	const hostedFields = sdpx.hostedfields.create(config);

	// Add event listeners 
	hostedFields.on("focus", evt => console.log(evt.fieldId + " Focused"));
	hostedFields.on("blur", evt => console.log(evt.fieldId + " Blurred"));
	hostedFields.on("empty", evt => console.log(evt.fieldId + " Empty"));
	hostedFields.on("valid", evt => console.log(evt.fieldId + " Valid"));
	hostedFields.on("invalid", evt => console.log(evt.fieldId + " Invalid"));
	hostedFields.on("field-ready", evt => console.log(evt.fieldId + " Field ready"));
	hostedFields.on("all-fields-ready", evt => console.log(evt.fieldId + " All fields ready"));
	hostedFields.on("error-init-fields", evt => console.log(evt.fieldId + " Error initiating fields"));
	hostedFields.on("card-brand-selected", evt => console.log(evt.fieldId + " Card brand selected"));
	hostedFields.on("card-brand-entry", evt => console.log(evt.fieldId + " Card brand entry"));
	hostedFields.on("error", evt => console.log(evt.fieldId + " error"));


	document.getElementById('payment-form').addEventListener('submit', (event) =>
	{
		const handleSubmit = async (onSuccess, onError) => {
		if (!hostedFieldsInstance) return;
		setIsSubmitting(true);
		setError(null);
		hostedFieldsInstance.tokenize(true).then(() => {
		console.log("Tokenize succeed");
		//CreatePayment via Server-to-server using apiResponse.hostedFieldSesssionId
		}).catch(err => console.error("Error"))
	} 
	});
}
</script>

The individual elements fulfil a specific role during the payment flow:

<form id="payment-form" novalidate>
 <div id="cardholderName"></div>
	 <div id="cardNumber"></div>
	 <div id="expiryDate"></div>
	 <div id="csc"></div>
	 <div id="cardBrands"></div>
<button id="submit-button" type="submit" disabled>Pay</button>
</form>

<script id="hosted-fields-sdk" crossorigin="anonymous"></script>

var apiResponse;

document.addEventListener('DOMContentLoaded', () => {
 
	const sdkScript = document.getElementById('hosted-fields-sdk');
	sdkScript.src = apiResponse.sdkUrl;
	sdkScript.integrity = 'sha256-${apiResponse.sdkSri}';
 
	sdkScript.onload = () => initializeHostedFields(apiResponse);
});

// Use our platform's response to initialise the  	
function initializeHostedFields(apiResponse) {
  ...
}

document.getElementById('payment-form').addEventListener('submit', (event) =>
	{
	const handleSubmit = async (onSuccess, onError) => {
    if (!hostedFieldsInstance) return;
    setIsSubmitting(true);
    setError(null);
    hostedFieldsInstance.tokenize(true).then(() => {
      console.log("Tokenize succeed");
      ///CreatePayment via Server-to-server using apiResponse.hostedFieldSesssionId
    }).catch(err => console.error("Error"))
		} 
	});

Initialise your system for sending requests to our Direct API by

• Defining test/live endpoint URLs.
• Activating your test/live PSPID on our platform.
• Setting up a test/live API Key/Secret pair.

Your web shop application's backend sends a CreateHostedFields request to our platform:

{ 
	"locale": "en-US"
}

If you want to pre‑fill the Hosted Fields with stored card data for 1-click payments, make sure to include property tokens in your request.

Endpoint Urls in test / live 

• Endpoint URL TEST: https://payment.preprod.direct.worldline-solutions.com/{merchantId}/hostedfields/sessions
• Endpoint URL LIVE: https://payment.direct.worldline-solutions.com/{merchantId}/hostedfields/sessions

Replace "{merchantId}" with your test/live account on our platform. Learn more about the "merchantId" in our glossary.

In our response, our platform will return the following data:

Load the Hosted Fields JavaScript library you have received in the previous step via object sessionData.

Add sessionData.sdkUrl as a separate <script> element to your checkout page containing the <form> element. For enhanced security, add sessionDate.sdrSri it as HTML attribute integrity.

The library is used in subsequent steps for

• Initialising the Hosted Fields.
• Tokenising the card data entered in the Hosted Fields.

<script id="hosted-fields-sdk" src="..." integrity="sha384-..." crossorigin="anonymous"></script>
document.addEventListener('DOMContentLoaded', () => {
 
	const sdkScript = document.getElementById('hosted-fields-sdk');
	sdkScript.src = apiResponse.sdkUrl;
	sdkScript.integrity = 'sha256-${apiResponse.sdkSri}';
	sdkScript.onload = () => initializeHostedFields(apiResponse);
});

As the value for src is different for each request, you need to dynamically/soft-code it. Mind that you need to load the script from our server rather than hosting it yourself.

Prepare a configuration object config using the sessionData object and initialise hostedFields. Add event listeners to react to user interactions (i.e. display errors, update the user interface).

The <button> event handler enables users to submit card data to our platform for tokenisation for the subsequent step.

function initializeHostedFields(apiResponse) {
	const submitButton = document.getElementById('submit-button');
	const resultDisplay = document.getElementById('result-display');
	const config = {
		"sessionData": apiResponse.sessionData,
		"logLevel": "debug",
		"style": {
			"input": {
			"color": "#000000",
			"font-family": "courier, monospace",
			"font-size": "14px"
			},
			"input::placeholder": {
				"color": "#999999"
				}
			},
		"fields": {
			"cardNumber": {
				"id": "cardNumber",
				"title": "Your card number",
				"placeholder": "0000 0000 0000 0000"
			},
			"cardholderName": {
				"id": "cardholderName",
				"title": "Your name",
				"placeholder": "John"
			},
			"cardBrands": {
				"id": "cardBrands",
				"title": "Your card brand",
				"placeholder": "VISA"
			},
			"expiryDate": {
				"id": "expiryDate",
				"caption": "Your card expiration date",
				"checkExpiredDate": "true",
				"placeholder": "MM/YY"
			},
			"csc": {
				"id": "csc",
				"title": "Your card security code",
				"caption": "Your card security code",
				"placeholder": "123"
			}
		}
	}

	const hostedFields = sdpx.hostedfields.create(config);

	// Add event listeners 
        hostedFields.on("focus", evt => console.log(evt.fieldId + " Focused"));
	hostedFields.on("blur", evt => console.log(evt.fieldId + " Blurred"));
	hostedFields.on("empty", evt => console.log(evt.fieldId + " Empty"));
	hostedFields.on("valid", evt => console.log(evt.fieldId + " Valid"));
	hostedFields.on("invalid", evt => console.log(evt.fieldId + " Invalid"));
	hostedFields.on("field-ready", evt => console.log(evt.fieldId + " Field ready"));
	hostedFields.on("all-fields-ready", evt => console.log(evt.fieldId + " All fields ready"));
	hostedFields.on("error-init-fields", evt => console.log(evt.fieldId + " Error initiating fields"));
	hostedFields.on("card-brand-selected", evt => console.log(evt.fieldId + " Card brand selected"));
	hostedFields.on("card-brand-entry", evt => console.log(evt.fieldId + " Card brand entry"));
	hostedFields.on("error", evt => console.log(evt.fieldId + " error"));

	document.getElementById('payment-form').addEventListener('submit', (event) =>
	{
	const handleSubmit = async (onSuccess, onError) => {
        if (!hostedFieldsInstance) return;
        setIsSubmitting(true);
        setError(null);
        hostedFieldsInstance.tokenize(true).then(() => {
      console.log("Tokenize succeed");
      //Create Payment S2S using apiResponse.hostedFieldSesssionId
    }).catch(err => console.error("Error"))
		} 
	});
}

This will insert <iframe> instances into the <div> elements in the <form> element. Each <iframe> loads a page containing an individual <input> field for each card data field:

Card number
Card holder name
Card brands
Expiry date
CVC

Your customers can now enter their card data in the fields.

Event handlers

The <iframe> elements listen for the following events/user interactions on each card data field:

Event data structure

The event object passed to your event handlers contains the following information:

Invalid event reasons

Your customers enter their card details in the <input> fields in the <form> element. Our platform detects the card scheme automatically once your customers start typing in the number. This also works for co-badged cards (where applicable). For every brand detected, our platform will display the respective logo(s) in <div id="cardBrands"></div>. All logos are clickable, allowing your customers to choose their preferred brand.

Once all card data fields have valid input, you can enable the <button> in the <form> element, allowing your customers to confirm the payment.

Your customers submit the card data to our platform via the <button> element, invoking the event listener you added to the <button> element when initialising the Hosted Fields. Our platform tokenises the card data and returns a hostedFieldsSessionId:

document.getElementById('paymentform').addEventListener('submit', (event) =>
{
	e.preventDefault();
	hostedFields.tokenize(true).then(()=> {
        
 const handleSubmit = async (onSuccess, onError) => {
    if (!hostedFieldsInstance) return;
    setIsSubmitting(true);
    setError(null);
    hostedFieldsInstance.tokenize(true).then(() => {
      console.log("Tokenize succeed");
      //Create Payment S2S using apiResponse.hostedFieldSesssionId
    }).catch(err => console.error("Error"))
  }

	console.log("Card Token:", token);
	}).catch(console.error);
});

You send a CreatePayment request to our platform via our Server-to-server integration method. Replace the card details with the hostedFieldsSessionId, including the mandatory 3-D Secure properties:

{
   "hostedFieldsSessionId": "apiResponse.sessionData.hostedFieldsSessionId", 
   "cardPaymentMethodSpecificInput":{
      "returnUrl":"https://yourReturnUrl.com"
   },
   "threeDSecure":{
      "skipAuthentication":false,
      "redirectionData":{
         "returnUrl":"https://yourReturnUrl.com"
      }
   },
   "order":{
      "amountOfMoney":{
         "amount":1000,
         "currencyCode":"EUR"
      },
      "customer":{
         "device":{
            "acceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
            "browserData":{
               "colorDepth":99,
               "javaEnabled":true,
               "javaScriptEnabled":true,
               "screenHeight":"768",
               "screenWidth":"1024"
            },
            "ipAddress":"123.123.123.123",
            "locale":"en_GB",
            "userAgent":"Mozilla/5.0(WindowsNT10.0;Win64;x64)AppleWebKit/537.36(KHTML,likeGecko)Chrome/75.0.3770.142Safari/537.36",
            "timezoneOffsetUtcMinutes":"-180"
         }
      }
   }
}

Our platform sends a response containing a merchantAction object.
It instructs you how to proceed with the payment. Based on the response, these scenarios are possible:

1. 3-D Secure frictionless flow: (merchantAction.actionType=null): Your customers use a 3-D Secure enrolled card. The 3-D Secure properties in your CreatePayment request prove to be sufficient for the authentication step. We submit the transaction to the acquirer and provide the result in property statusOutput.statusCode.
2. 3-D Secure challenge flow: (merchantAction.actionType="REDIRECT"): Your customers use a 3-D Secure enrolled card. They need to identify themselves as the rightful card owner. Redirect them to their issuer via the merchantAction.redirectData.redirectURL. Define a cardPaymentMethodSpecificInput.returnUrl in the initial CreatePayment request to make sure your customers are redirected to your webshop afterwards.
3. No 3-D Secure authentication (merchantAction.actionType=null): Your customers use a non-3-D Secure enrolled card. We submit the transaction to the acquirer and provide the result in property statusOutput.statusCode.

Depending on the scenario, getting and showing the transaction / 3-D Secure result differs:

3-D Secure frictionless flow/No 3-D Secure authentication

Your customers remain in your webshop. Adapt your webshop checkout page according to the statusOutput.statusCode as returned from the initial CreatePayment request.

3-D Secure challenge flow:

We receive the transaction / 3-D Secure result redirect your customers to your webshop. Define a cardPaymentMethodSpecificInput.returnUrl in the initial CreatePayment request for this redirection. Make sure to implement a mechanism on this returnUrl that notifies your server about this redirection. Upon receiving this notification, send a GetPaymentDetails request to get the transaction result. Use the payment.id from the initial CreatePayment request:

Adapt the returnUrl depending on the statusOutput.statusCode as returned from this GetPaymentDetails request.

Learn in our dedicated Status guide more about the properties from the response, their meaning and how to proceed appropriately depending on the transactions' status.