Hosted Fields

Notre solution Hosted Fields nécessite que votre page de checkout implémente des éléments HTML/

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

Les différents éléments remplissent un rôle spécifique dans la cinématique de paiement :

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

Initialisez votre système pour l’envoi de requêtes vers notre API Direct en :

• Définissant les URLs des endpoints de test et de production.
• Activant votre PSPID test/production sur notre plateforme.
• Configurant une paire clé / secret d’API pour les environnements de test et de production.

Le backend de l’application de votre boutique en ligne envoie une requête CreateHostedFields à notre plateforme :

{ 
	"locale": "en-US"
}

Si vous souhaitez préremplir les Hosted Fields avec des données de carte enregistrées pour des paiements en 1‑clic, veillez à inclure la propriété tokens dans votre requête.

URLs des endpoints en test / production 

• 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

Remplacez « {merchantId} » par votre compte test/production sur notre plateforme. Pour en savoir plus sur le « merchantId », consultez notre glossaire.

Dans notre réponse, notre plateforme renvoie les données suivantes :

Chargez la bibliothèque JavaScript Hosted Fields que vous avez reçue à l’étape précédente via l’objet sessionData.

Ajoutez sessionData.sdkUrl comme élément <script> distinct sur votre page de checkout contenant l’élément <form>. Pour renforcer la sécurité, ajoutez sessionDate.sdrSri comme attribut HTML integrity.

La bibliothèque est utilisée dans les étapes suivantes pour :

• initialiser les Hosted Fields ;
• tokeniser les données de carte saisies dans les 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);
});

Comme la valeur de l’attribut src est différente pour chaque requête, vous devez la définir dynamiquement (soft‑coding). Veillez à charger le script depuis notre serveur plutôt que de l’héberger vous‑même.

Préparez un objet de configuration config à partir de l’objet sessionData et initialisez hostedFields. Ajoutez des gestionnaires d’événements (event listeners) pour réagir aux interactions utilisateur (par ex. afficher des erreurs, mettre à jour l’interface).

Le gestionnaire d’événement du bouton <button> permet aux utilisateurs d’envoyer les données de carte à notre plateforme pour tokenisation à l’étape suivante.

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

Cela insère des instances <iframe> dans les éléments <div> du formulaire <form>. Chaque <iframe> charge une page contenant un champ <input> individuel pour chaque donnée de carte :

Numéro de carte
Nom du porteur de carte
Marque de carte
Date d’expiration
CVC

Vos clients peuvent maintenant saisir leurs données de carte dans ces champs.

Gestionnaires d’événements

Les éléments <iframe> écoutent les événements / interactions utilisateur suivants sur chaque champ de données de carte :

Structure des données d’événement

L’objet événement transmis à vos gestionnaires contient les informations suivantes :

Raisons d’invalidité

Vos clients saisissent leurs coordonnées de carte dans les champs <input> de l’élément <form>. Notre plateforme détecte automatiquement le schéma de paiement dès que vos clients commencent à taper le numéro de carte. Cela fonctionne également pour les cartes co-badgées (le cas échéant). Pour chaque marque détectée, notre plateforme affiche le(s) logo(s) correspondant(s) dans <div id="cardBrands"></div>. Tous les logos sont cliquables, ce qui permet à vos clients de choisir leur marque préférée.

Une fois que tous les champs de données de carte contiennent des valeurs valides, vous pouvez activer le bouton <button> dans l’élément <form>, afin de permettre à vos clients de confirmer le paiement.

Vos clients soumettent les données de carte à notre plateforme via l’élément <button>, ce qui déclenche le gestionnaire d’événement que vous avez ajouté à cet élément lors de l’initialisation des Hosted Fields. Notre plateforme tokenise alors les données de carte et renvoie un 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);
});

Vous envoyez une requête CreatePayment à notre plateforme via notre Server-to-server mode d'intégration. Remplacez les données de carte par le hostedFieldsSessionId, en incluant les propriétés 3-D Secure obligatoires :

{
   "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.