Documentation
Documentation
Boîte à lumière

1Introduction

Pour créer un paiement via la plateforme, vous avez le choix entre la payment page integration, où le client est redirigé vers notre page de paiement, la iframe integration, où le formulaire de paiement est placé dans un iframe à l’aide de notre intégration JavaScript, ou la lightbox integration, afin d’obtenir une intégration transparente et conforme PCI DSS dans votre checkout.

L’intégration lightbox permet d’afficher le formulaire de collecte des informations de paiement sous forme de fenêtre en superposition dans le checkout, une fois la commande confirmée. Cela permet le processus suivant (simplifié) dans l’application du marchand :

  1. Facultatif : le client sélectionne le mode de paiement.

  2. Le client soumet la commande, qui est alors créée.

  3. La lightbox s’affiche, dans laquelle le client peut choisir le mode de paiement (si cela n’a pas été fait à l’étape 1) et saisir ses informations de paiement.

L’avantage de cette intégration par rapport à la page de paiement est que l’intégration est transparente et que le client ne remarque jamais qu’il quitte le site web du marchand. De plus, l’intégration lightbox est moins compliquée que l’intégration iframe.

Intégration lightbox transparente
Figure 1. L’image montre un exemple d’intégration lightbox transparente.

2Détails de l’intégration lightbox

Avant de commencer l’intégration de la lightbox, vous devriez :

  1. Créer un compte et vous inscrire.

  2. Créer un utilisateur d’application sous Account > Utilisateurs > Utilisateur d’application.

  3. Apprendre à vous authentifier et vous connecter à notre web service.

Note
 Veuillez consulter notre dépôt GitHub où nous proposons des SDKs prêts à télécharger dans différents langages, qui facilitent considérablement vos efforts d’intégration.

Nous vous proposons également un API Client qui vous permet de tester les requêtes envoyées à l’API et de consulter les réponses.

3Interactions système

lightbox
Figure 2. Diagramme de séquence de l’intégration lightbox

3.1Processus

Nous décrivons ci-dessous le processus d’intégration en détail. Pour mieux le comprendre, consultez le diagramme des interactions système ci-dessus.

  1. Créez un objet transaction avec le Transaction Service. Pour créer un objet transaction, vous pouvez fournir toutes les informations dont vous disposez à ce stade. Plus vous fournissez d’informations, mieux nous pouvons prévalider les données et éventuellement exclure certains modes de paiement qui ne fonctionneront pas pour ces données. La plupart des données fournies peuvent être mises à jour avant que la transaction ne soit effectivement confirmée.

  2. Une fois l’objet transaction créé, les modes de paiement possibles peuvent être récupérés en utilisant récupérer les modes de paiement possibles sur le Transaction Service, en fournissant le transactionId retourné par la requête initiale et le mode d’intégration lightbox. La méthode retourne tous les modes de paiement adaptés à la transaction actuelle. La méthode peut être utilisée soit pour vérifier si un mode de paiement particulier est actif, soit pour afficher tous les modes de paiement disponibles. Cela dépend du cas d’utilisation.

  3. Pour collecter les informations de paiement dans la lightbox, vous devez inclure un fichier JavaScript sur la page web depuis laquelle la lightbox doit être ouverte. L’URL de ce fichier JavaScript peut être récupérée via buildJavaScriptUrl. Incluez le script à l’aide de la balise <script>.

  4. Appelez la fonction JavaScript LightboxCheckoutHandler.startPayment(paymentMethod, errorCallback) pour afficher la lightbox. Cette fonction accepte deux arguments facultatifs :

    paymentMethod

    Passez l’ID de la configuration du mode de paiement à la fonction pour présélectionner ce mode. Si cet argument est omis, le client peut sélectionner le mode de paiement dans la lightbox.

    errorCallback

    Une fonction JavaScript peut être passée comme deuxième argument ; elle sera appelée en cas d’erreur lors de l’ouverture de la lightbox.

  5. Après que le client a saisi ses informations de paiement et que le paiement a été traité (ou a échoué), le client est redirigé vers la successUrl (ou la failedUrl) définie sur l’objet transaction.

  6. Écoutez la notification sur l’URL de webhook définie pour marquer la commande dans le système du marchand comme authorized ou failed. Cet écouteur de notifications est important car le client peut fermer la fenêtre avant de revenir à l’application du marchand. L’état de la transaction peut être récupéré à tout moment via l’API.

3.2Détails techniques

Les étapes décrites ci-dessus vont maintenant être expliquées un peu plus en détail, y compris les opérations API avec des exemples de requêtes.

3.2.1Configuration côté client

L’acceptation des paiements via la lightbox offre un moyen transparent de collecter les informations de paiement de vos clients. Cette méthode est non seulement intégrée de manière transparente, elle répond également à toutes les exigences PCI DSS pour les marchands afin de vous maintenir autant que possible hors du périmètre, tout en offrant un parcours de paiement intégré.

Vous trouverez ci-dessous un exemple de configuration côté client.

<button id="pay-button">Pay</button>

<script src="jquery.js" type="text/javascript"></script>
<script src="{ JavaScript URL }" type="text/javascript"></script>
<script type="text/javascript">
// Set here the id of the payment method configuration the customer chose.
var paymentMethodConfigurationId = 1;

$('#pay-button').on('click', function(){
	window.LightboxCheckoutHandler.startPayment(paymentMethodConfigurationId, function(){
		alert('An error occurred during the initialization of the payment lightbox.');
	});
});
</script>

3.2.2Créer un objet transaction

Pour créer un objet transaction, vous devez utiliser la fonction de création de transaction. Vous y fournissez les informations client dont vous disposez, y compris les lignes d’articles et les prix. Cela créera une transaction pending dans votre Space.

Note
 Fournissez autant d’informations que vous avez pu collecter auprès de votre client à ce stade. Plus nous avons d’informations, plus la sélection des modes de paiement possibles sera précise.

Requête

{
   "billingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"some-buyer@customweb.com",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"General-Guisan-Strasse 47"
   },
   "currency":"EUR",
   "language":"de-CH",
   "lineItems":[
	  {
		 "amountIncludingTax":"11.87",
		 "name":"Barbell Pull Up Bar",
		 "quantity":"1",
		 "shippingRequired":"true",
		 "sku":"barbell-pullup",
		 "type":"PRODUCT",
		 "uniqueId":"barbell-pullup"
	  },
	  {
		 "amountIncludingTax":"559",
		 "name":"Rowing Machine",
		 "quantity":"1",
		 "shippingRequired":"true",
		 "sku":"rowing-machine",
		 "type":"PRODUCT",
		 "uniqueId":"rowing-machine"
	  },
	  {
		 "amountIncludingTax":"17.98",
		 "name":"Super Whey Protein",
		 "quantity":"4",
		 "shippingRequired":"true",
		 "sku":"super-whey",
		 "taxes":[
			{
			   "rate":"10",
			   "title":"VAT"
			},
			{
			   "rate":"3.5",
			   "title":"Supplement Fee"
			}
		 ],
		 "type":"PRODUCT",
		 "uniqueId":"super-whey"
	  },
	  {
		 "amountIncludingTax":"12.5",
		 "name":"Special Chär Test",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"special-chär-test",
		 "type":"SHIPPING",
		 "uniqueId":"special-chär-test"
	  },
	  {
		 "amountIncludingTax":"12.5",
		 "name":"Standard Shipping",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"standard-shipping",
		 "type":"SHIPPING",
		 "uniqueId":"standard-shipping"
	  },
	  {
		 "amountIncludingTax":"-10",
		 "name":"Spring Discount",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"spring-discount",
		 "type":"DISCOUNT",
		 "uniqueId":"spring-discount"
	  }
   ],
   "merchantReference":"DEV-2630",
   "shippingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"some-buyer@customweb.com",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"General-Guisan-Strasse 47"
   }
}

Réponse

La réponse que vous recevrez contient l'`id` (dans l’exemple ci-dessous 109472) qui sera désormais utilisé pour effectuer d’autres opérations sur cette transaction.

{
	"allowedPaymentMethodBrands": [],
	"allowedPaymentMethodConfigurations": [],
	"authorizationAmount": 603.85,
	"authorizationTimeoutOn": "2017-12-07T08:44:09.119Z",
	"autoConfirmationEnabled": true,
	"chargeRetryEnabled": true,
	"confirmedBy": 0,
	"createdBy": 0,
	"createdOn": "2017-12-07T08:14:09.119Z",
	"currency": "EUR",
	"customersPresence": "VIRTUAL_PRESENT",
	"endOfLife": "2017-12-21T08:14:09.119Z",
	"group": {
		"id": 109478
	},
	"id": 109472,
	"language": "de-CH",
	"linkedSpaceId": 396,
	"metaData": {},
	"plannedPurgeDate": "2017-12-21T08:14:09.119Z",
	"refundedAmount": 0,
	"state": "PENDING",
	"timeZone": "Z",
	"version": 1
}

3.2.3Construire l’URL JavaScript

Pour obtenir l’URL du JavaScript, vous pouvez utiliser l’opération buildJavaScriptUrl afin d’obtenir une URL pointant vers le JavaScript qui doit être inclus dans votre checkout pour créer la lightbox. Insérez le JavaScript sur la page où la lightbox doit être affichée, comme indiqué dans l’exemple côté client ci-dessus.

3.2.4Récupérer les modes de paiement possibles

Pour intégrer l’iframe de manière transparente dans votre checkout, vous devrez récupérer les modes de paiement possibles et afficher les options dans le checkout.

Cela retournera l'`id` du mode de paiement, qui doit ensuite être défini dans le JavaScript à l’aide du paymentMethodConfigurationId.

Réponse

La réponse retourne les modes de paiement possibles pour le transactionId donné.

{
	"data": [{
		"dataCollectionType": "ONSITE",
		"description": {
			"en-US": ""
		},
		"id": 510,
		"imageResourcePath": null,
		"linkedSpaceId": 396,
		"name": "Credit / Debit Card",
		"oneClickPaymentMode": "ALLOW",
		"paymentMethod": {
			"id": 1457546097597
		},
		"plannedPurgeDate": null,
		"resolvedDescription": {
			"en-US": "Pay conveniently with your credit or debit card."
		},
		"resolvedImageUrl": "https://app-wallee.com/s/396/resource/icon/payment/method/credit-debit-card.svg",
		"resolvedTitle": {
			"en-US": "Credit / Debit Card"
		},
		"sortOrder": 1,
		"spaceId": 396,
		"state": "ACTIVE",
		"title": {
			"en-US": ""
		},
		"version": 2
	}],
	"hasMore": false,
	"limit": 1
}

3.2.5Mettre à jour des transactions

Les propriétés d’une transaction peuvent être mises à jour tant qu’elle n’est pas à l’état confirmed. Pour ce faire, utilisez l’opération update sur le service Transaction.

Note
 Consultez la section Versionnage / Verrouillage des objets qui décrit comment gérer la propriété version pour éviter les conflits de verrouillage optimiste.

Requête

Dans l’exemple ci-dessous, nous allons mettre à jour les lignes d’articles et supprimer la ligne de remise que nous avons ajoutée dans l’exemple précédent.

{
	"billingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@customweb.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "General-Guisan-Strasse 47"
	},
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"lineItems": [
		{
			"amountIncludingTax": "11.87",
			"name": "Barbell Pull Up Bar",
			"quantity": "1",
			"sku": "barbell-pullup",
			"type": "PRODUCT",
			"uniqueId": "barbell-pullup"
		},
		{
			"amountIncludingTax": "559",
			"name": "Rowing Machine",
			"quantity": "1",
			"sku": "rowing-machine",
			"type": "PRODUCT",
			"uniqueId": "rowing-machine"
		},
		{
			"amountIncludingTax": "17.98",
			"name": "Super Whey Protein",
			"quantity": "4",
			"sku": "super-whey",
			"type": "PRODUCT",
			"uniqueId": "super-whey"
		},
		{
			"amountIncludingTax": "12.5",
			"name": "Special Chär Test",
			"quantity": "1",
			"sku": "special-chär-test",
			"type": "SHIPPING",
			"uniqueId": "special-chär-test"
		},
		{
			"amountIncludingTax": "12.5",
			"name": "Standard Shipping",
			"quantity": "1",
			"sku": "standard-shipping",
			"type": "SHIPPING",
			"uniqueId": "standard-shipping"
		}
	],
	"shippingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@customweb.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "General-Guisan-Strasse 47"
	},
	"version": 3
}

Réponse

La réponse contient l’objet transaction mis à jour.

{
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"version": 3
}

3.2.6Confirmer la transaction

Si la propriété de confirmation automatique n’est pas définie, la transaction doit être confirmée. Nous recommandons d’effectuer cette étape dans tous les cas.

L’étape de confirmation de la transaction doit être effectuée une fois que les saisies du client ont été validées et que la commande en attente a été créée dans votre application (voir l’étape 7 du processus ci-dessus). Vous pouvez utiliser la fonction de confirmation pour confirmer la transaction et également définir la merchant reference, puisque vous disposez maintenant d’un numéro de commande dans votre application.

Requête

{
	"billingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@customweb.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "General-Guisan-Strasse 47"
	},
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"lineItems": [
		{
			"amountIncludingTax": "11.87",
			"name": "Barbell Pull Up Bar",
			"quantity": "1",
			"sku": "barbell-pullup",
			"type": "PRODUCT",
			"uniqueId": "barbell-pullup"
		},
	 ],
	"merchantReference": "DEV-2630",
	"shippingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@customweb.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "General-Guisan-Strasse 47"
	},
	"version": 5
}

3.2.7Récupérer les mises à jour de la transaction

Pour être informé de l’état de la transaction, vous devriez enregistrer des notifications webhook de votre côté. Les webhooks vous informent des changements d’état des entités sélectionnées et devraient déclencher dans votre application le traitement ultérieur des résultats de la transaction.

Vous trouverez plus d’informations sur les webhooks, les écouteurs de webhooks et leur configuration dans la documentation des webhooks.

4Politique de sécurité

Si des restrictions de Content Security Policy sont appliquées dans la boutique, pour que cette intégration fonctionne, les restrictions suivantes doivent être levées pour https://app-wallee.com :

  • Les URLs pouvant être chargées comme sources valides pour JavaScript.

  • Autoriser l’exécution de scripts inline.

  • Les URLs pouvant être chargées via des interfaces iframe.

  • Les URLs pouvant être chargées via des interfaces de script.

Par exemple, l’en-tête suivant le permettrait en définissant la directive CSP: script-src pour autoriser le chargement des URLs https://app-wallee.com comme sources valides pour JavaScript, la politique Unsafe inline script pour autoriser l’exécution de scripts inline, la directive CSP: frame-src pour autoriser le chargement des URLs https://app-wallee.com via des interfaces iframe, et la directive CSP: connect-src pour autoriser le chargement des URLs https://app-wallee.com via des interfaces de script.

content-security-policy: script-src https://app-wallee.com 'unsafe-inline'; frame-src https://app-wallee.com; connect-src https://app-wallee.com;