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"
         }
      }
   }
}

Notre plateforme envoie une réponse contenant un objet merchantAction.
Elle vous indique comment procéder avec le paiement. Selon la réponse, ces scénarios sont possibles :

1. Cinématique d'authentification frictionless ou passive 3-D Secure : (merchantAction.actionType=null) : Vos clients utilisent une carte inscrite au 3-D Secure. Les propriétés 3-D Secure dans votre requête CreatePayment s'avèrent suffisantes pour l'étape d'authentification. Nous soumettons la transaction à l'acquéreur et fournissons le résultat dans la propriété statusOutput.statusCode.
2. cinématique d'authentification forte 3-D Secure : (merchantAction.actionType="REDIRECT") : Vos clients utilisent une carte inscrite au 3-D Secure. Ils doivent s'identifier en tant que détenteur légitime de la carte. Redirigez-les vers leur émetteur via le merchantAction.redirectData.redirectURL. Définissez une cardPaymentMethodSpecificInput.returnUrl dans la requête CreatePayment initiale pour vous assurer que vos clients sont redirigés vers votre boutique en ligne par la suite.
3. Pas d'authentification 3-D Secure (merchantAction.actionType=null) : Vos clients utilisent une carte non inscrite au 3-D Secure. Nous soumettons la transaction à l'acquéreur et fournissons le résultat dans la propriété statusOutput.statusCode.

Selon le scénario, l'obtention et l'affichage du résultat de la transaction / 3-D Secure diffère :

Cinématique Frictionless/Pas d'authentification 3-D Secure

Vos clients restent sur votre boutique en ligne. Adaptez la page de paiement de votre boutique en ligne selon le statusOutput.statusCode tel que retourné par la requête initiale CreatePayment.

Cinématique Challenge

Nous recevons le résultat de la transaction / 3-D Secure et redirigeons vos clients vers votre boutique en ligne. Définissez un cardPaymentMethodSpecificInput.returnUrl dans la requête initiale CreatePayment pour cette redirection. Assurez-vous d'implémenter un mécanisme sur ce returnUrl qui notifie votre serveur de cette redirection. Dès réception de cette notification, envoyez une requête GetPaymentDetails pour obtenir le résultat de la transaction. Utilisez le payment.id de la requête initiale CreatePayment :

Adaptez le returnUrl en fonction du statusOutput.statusCode tel que retourné par cette requête GetPaymentDetails.

Découvrez dans notre guide des statuts plus d'informations sur les propriétés de la réponse, leur signification et comment procéder de manière appropriée en fonction du statut des transactions.