Dokumentation
Dokumentation
Lightbox

1Einleitung

Um eine Zahlung über die Plattform zu erstellen, haben Sie die Wahl zwischen der payment page integration, bei der der Kunde auf unsere Zahlungsseite weitergeleitet wird, der iframe integration, bei der das Zahlungsformular über unsere JavaScript-Integration in einem iframe platziert wird, oder der lightbox integration, um eine nahtlose und PCI-DSS-konforme Integration in Ihrem Checkout zu erreichen.

Die Lightbox-Integration ermöglicht es, das Formular zur Erfassung der Zahlungsinformationen als Overlay-Box im Checkout anzuzeigen, nachdem die Bestellung bestätigt wurde. Dies ermöglicht den folgenden (vereinfachten) Prozess in der Händleranwendung:

  1. Optional: Der Kunde wählt die Zahlart aus.

  2. Der Kunde sendet die Bestellung ab, die daraufhin erstellt wird.

  3. Die Lightbox wird angezeigt, in der der Kunde die Zahlart wählen (falls nicht bereits in Schritt 1 geschehen) und seine Zahlungsinformationen eingeben kann.

Der Vorteil dieser Integration gegenüber der Zahlungsseite besteht darin, dass die Integration nahtlos ist und der Kunde nie bemerkt, dass die Händler-Website verlassen wird. Ausserdem ist die Lightbox-Integration weniger kompliziert als die iframe-Integration.

Nahtlose Lightbox-Integration
Figure 1. Das Bild zeigt ein Beispiel einer nahtlosen Lightbox-Integration.

2Details zur Lightbox-Integration

Bevor Sie mit der Integration der Lightbox beginnen, sollten Sie:

  1. Ein Konto erstellen und sich registrieren.

  2. Einen Anwendungsbenutzer unter Account > Benutzer > Anwendungsbenutzer erstellen.

  3. Lernen, wie Sie sich bei unserem Web Service authentifizieren und verbinden.

Note
 Werfen Sie bitte einen Blick auf unser GitHub-Repository, in dem wir fertige SDKs in verschiedenen Sprachen zum Download anbieten, die Ihren Integrationsaufwand drastisch reduzieren.

Wir bieten Ihnen auch einen API Client an, mit dem Sie die an die API gesendeten Anfragen testen und die Antworten einsehen können.

3Systeminteraktionen

lightbox
Figure 2. Sequenzdiagramm der Lightbox-Integration

3.1Prozess

Nachfolgend beschreiben wir den Integrationsprozess im Detail. Um dies besser zu verstehen, werfen Sie einen Blick auf das obige Systeminteraktionsdiagramm.

  1. Erstellen Sie ein Transaktionsobjekt mit dem Transaction Service. Beim Erstellen eines Transaktionsobjekts können Sie alle Informationen angeben, die Ihnen zu diesem Zeitpunkt vorliegen. Je mehr Informationen Sie angeben, desto besser können wir die Daten vorvalidieren und möglicherweise einige Zahlarten ausschliessen, die für diese Daten nicht funktionieren. Die meisten der angegebenen Daten können aktualisiert werden, bevor die Transaktion tatsächlich bestätigt wird.

  2. Sobald das Transaktionsobjekt erstellt ist, können die möglichen Zahlarten über mögliche Zahlarten abrufen auf dem Transaction Service abgerufen werden, indem die von der ursprünglichen Anfrage zurückgegebene transactionId und der Integrationsmodus lightbox angegeben werden. Die Methode gibt alle Zahlarten zurück, die für die aktuelle Transaktion geeignet sind. Die Methode kann entweder verwendet werden, um zu prüfen, ob eine bestimmte Zahlart aktiv ist, oder um alle verfügbaren Zahlarten darzustellen. Dies hängt vom Anwendungsfall ab.

  3. Um die Zahlungsinformationen in der Lightbox zu erfassen, müssen Sie eine JavaScript-Datei auf der Webseite einbinden, von der aus die Lightbox geöffnet werden soll. Die URL zu dieser JavaScript-Datei kann über buildJavaScriptUrl abgerufen werden. Binden Sie das Skript über das <script>-Tag ein.

  4. Rufen Sie die JavaScript-Funktion LightboxCheckoutHandler.startPayment(paymentMethod, errorCallback) auf, um die Lightbox anzuzeigen. Diese Funktion akzeptiert zwei optionale Argumente:

    paymentMethod

    Übergeben Sie der Funktion die ID der Zahlartenkonfiguration, um diese Zahlart vorzuwählen. Wird dieses Argument weggelassen, kann der Kunde die Zahlart in der Lightbox auswählen.

    errorCallback

    Als zweites Argument kann eine JavaScript-Funktion übergeben werden, die im Falle eines Fehlers beim Öffnen der Lightbox aufgerufen wird.

  5. Nachdem der Kunde seine Zahlungsinformationen eingegeben hat und die Zahlung verarbeitet wurde (oder fehlgeschlagen ist), wird der Kunde auf die im Transaktionsobjekt definierte successUrl (oder failedUrl) weitergeleitet.

  6. Warten Sie auf die Benachrichtigung an der definierten Webhook-URL, um die Bestellung im Händlersystem als authorized oder failed zu markieren. Dieser Benachrichtigungs-Listener ist wichtig, da der Kunde das Fenster möglicherweise schliesst, bevor er zur Händleranwendung zurückkehrt. Der Status der Transaktion kann jederzeit über die API abgerufen werden.

3.2Technische Details

Die oben beschriebenen Schritte werden nun etwas detaillierter erläutert, einschliesslich der API-Operationen mit Beispielanfragen.

3.2.1Client-seitige Einrichtung

Die Zahlungsannahme über die Lightbox bietet eine nahtlose Möglichkeit, Zahlungsinformationen von Ihren Kunden zu erfassen. Diese Methode ist nicht nur nahtlos integriert, sie erfüllt auch alle PCI-DSS-Anforderungen für Händler, um Sie so weit wie möglich aus dem Geltungsbereich herauszuhalten, und erreicht dennoch einen integrierten Checkout-Ablauf.

Nachfolgend finden Sie ein Beispiel für die client-seitige Einrichtung.

<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.2Erstellen eines Transaktionsobjekts

Um ein Transaktionsobjekt zu erstellen, müssen Sie die Operation zum Erstellen von Transaktionen verwenden. Hier geben Sie die Ihnen vorliegenden Kundendaten an, einschliesslich der Positionen und Preise. Dadurch wird eine pending Transaktion in Ihrem Space erstellt.

Note
 Geben Sie so viele Informationen an, wie Sie zu diesem Zeitpunkt von Ihrem Kunden erfassen konnten. Je mehr Informationen wir haben, desto genauer wird die Auswahl der möglichen Zahlarten sein.

Anfrage

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

Antwort

Die Antwort, die Sie erhalten, enthält die id (im untenstehenden Beispiel 109472), die nun verwendet wird, um weitere Operationen mit dieser Transaktion durchzuführen.

{
	"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.3Erstellen der JavaScript-URL

Um die URL zur JavaScript-URL zu erhalten, können Sie die Operation buildJavaScriptUrl verwenden, um eine URL zu erhalten, die auf das JavaScript zeigt, das in Ihrem Checkout eingebunden werden sollte, um die Lightbox zu erstellen. Fügen Sie das JavaScript auf Ihrer Seite ein, auf der die Lightbox angezeigt werden soll, wie im obigen client-seitigen Beispiel gezeigt.

3.2.4Abrufen der möglichen Zahlarten

Um das iframe nahtlos in Ihren Checkout zu integrieren, müssen Sie die möglichen Zahlarten abrufen und die Optionen im Checkout darstellen.

Dies gibt die id der Zahlart zurück, die dann im JavaScript über die paymentMethodConfigurationId gesetzt werden sollte.

Antwort

Die Antwort gibt die möglichen Zahlarten für die angegebene transactionId zurück.

{
	"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://staging-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.5Aktualisieren von Transaktionen

Transaktionseigenschaften können aktualisiert werden, solange sie sich nicht im Status confirmed befinden. Verwenden Sie dazu die update Operation auf dem Transaction Service.

Note
 Werfen Sie einen Blick auf den Abschnitt Objektversionierung / Sperrung, der beschreibt, wie Sie die version Eigenschaft handhaben müssen, um Konflikte durch optimistisches Sperren zu verhindern.

Anfrage

Im untenstehenden Beispiel aktualisieren wir die Positionen und entfernen die Rabattposition, die wir im obigen Beispiel hinzugefügt haben.

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

Antwort

Die Antwort enthält das aktualisierte Transaktionsobjekt.

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

3.2.6Bestätigen der Transaktion

Falls die Auto-Confirm-Eigenschaft nicht gesetzt ist, muss die Transaktion bestätigt werden. Wir empfehlen, diesen Schritt in jedem Fall durchzuführen.

Der Schritt zur Bestätigung der Transaktion sollte durchgeführt werden, sobald die Eingaben des Kunden validiert wurden und die ausstehende Bestellung in Ihrer Anwendung erstellt wurde (siehe Schritt 7 im obigen Prozess). Sie können die Confirm-Operation verwenden, um die Transaktion zu bestätigen und auch die merchant reference zu setzen, da Sie nun eine Bestellnummer in Ihrer Anwendung haben.

Anfrage

{
	"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.7Abrufen von Transaktionsaktualisierungen

Um über den Status der Transaktion auf dem Laufenden zu bleiben, sollten Sie auf Ihrer Seite Webhook-Benachrichtigungen registrieren. Die Webhooks informieren Sie über Statusänderungen der ausgewählten Entitäten und sollten Ihre Anwendung dazu veranlassen, die Transaktionsergebnisse weiterzuverarbeiten.

Weitere Informationen zu Webhooks, Webhook-Listenern und deren Konfiguration finden Sie in der Webhook-Dokumentation.

4Sicherheitsrichtlinie

Wenn im Shop Content-Security-Policy-Einschränkungen angewendet werden, müssen die folgenden Einschränkungen für https://staging-wallee.com entfernt werden, damit diese Integration funktioniert:

  • URLs, die als gültige Quellen für JavaScript geladen werden können.

  • Erlauben von Inline-Skript-Ausführungen.

  • URLs, die über iframe-Schnittstellen geladen werden können.

  • URLs, die über Skript-Schnittstellen geladen werden können.

Zum Beispiel würde der folgende Header dies erlauben, indem die CSP: script-src Direktive so gesetzt wird, dass https://staging-wallee.com URLs als gültige Quellen für JavaScript geladen werden dürfen, die Unsafe inline script Richtlinie Inline-Skript-Ausführungen erlaubt, die CSP: frame-src Direktive das Laden von https://staging-wallee.com URLs über iframe-Schnittstellen erlaubt und die CSP: connect-src Direktive das Laden von https://staging-wallee.com URLs über Skript-Schnittstellen erlaubt.

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