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.
Ziel der Iframe-Integration ist es, die Erfassung und Validierung der Zahlungsinformationen zu ermöglichen, bevor die eigentliche Bestellung vom Kunden bestätigt wird. Das Iframe kann z.B. eingebettet werden, bevor die Bestellung in der Händleranwendung tatsächlich abgeschlossen wird. Dies ermöglicht den folgenden (vereinfachten) Prozess in der Händleranwendung:
-
Der Kunde gibt die Versand- und Rechnungsinformationen ein.
-
Der Benutzer wählt die Zahlart aus. Die Anwendung bettet das Iframe mit dem Formular zur Erfassung zusätzlicher Zahlungsinformationen ein. Das Formular hängt von der Zahlart und unter Umständen sogar vom Connector ab.
-
Die Anwendung kann eine Validierung der eingegebenen Informationen auslösen.
-
Der Benutzer kann die Bestellung bestätigen, und die Anwendung meldet uns den endgültigen Status der Transaktion. Danach wird das Iframe mit JavaScript abgeschickt. Das Iframe kann nach der Validierung der Daten ausgeblendet werden. Das Abschicken löst ein Ausbrechen aus dem Frame aus.
Der Vorteil dieser Integration gegenüber der Zahlungsseite ist, dass die Integration nahtlos ist und der Kunde nie bemerkt, dass die Händler-Website verlassen wird. Ausserdem können die Zahlungsinformationen eingegeben werden, bevor die Bestellung abgeschlossen werden muss. Das bedeutet, dass die Bestellnummer angegeben werden kann, nachdem die Zahlungsinformationen erfasst wurden. Allerdings ist die Integration komplizierter als die Integration der Zahlungsseite.
Figure 1. Das Bild zeigt ein Beispiel einer nahtlosen Iframe-Integration
Bevor Sie mit der Integration des Iframes beginnen, sollten Sie:
-
Einen Anwendungsbenutzer unter Account > Benutzer > Anwendungsbenutzer erstellen.
-
Lernen, wie Sie sich bei unserem Webservice authentifizieren und verbinden.
|
Note
|
Werfen Sie bitte einen Blick auf unser github Repository, wo wir
fertige SDK 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.
Figure 2. Sequenzdiagramm der Iframe-Integration
Nachfolgend beschreiben wir den Integrationsprozess im Detail. Um dies besser zu verstehen, werfen Sie einen Blick auf das Systeminteraktionsdiagramm oben.
-
Erstellen Sie ein Transaktionsobjekt mit dem
Transaction Service. Beim Erstellen eines Transaktionsobjekts können Sie alle Informationen angeben, die Sie zu diesem Zeitpunkt haben. Je mehr Informationen Sie angeben, desto besser können wir die Daten vorvalidieren und eventuell einige Zahlarten ausschliessen, die mit den Daten nicht funktionieren. Die meisten der angegebenen Daten können geändert werden, bevor die Transaktion tatsächlich bestätigt wird. -
Sobald das Transaktionsobjekt erstellt ist, können die möglichen Zahlarten über mögliche Zahlarten abrufen auf dem
Transaction Serviceabgerufen werden, indem die vom ersten Request zurückgegebenetransactionIdund der Integrationsmodusiframeangegeben werden. Die Methode gibt alle Zahlarten zurück, die für die aktuelle Transaktion aktiv sind. Die Methode kann verwendet werden, um zu prüfen, ob eine bestimmte Zahlart aktiv ist, oder um alle verfügbaren Zahlarten darzustellen. Dies hängt von der Händleranwendung ab. -
Um das Iframe in die Website einzubetten, muss eine JavaScript-URL abgerufen werden. Dafür kann die Servicemethode JavaScript-URL erstellen verwendet werden. Die von der Servicemethode zurückgegebene URL verweist auf die JavaScript-Datei, die eingebettet werden muss. Es genügt, sie nur einmal einzubetten und nicht für jede Zahlart. Das Skript kann mit dem
<script>-Tag eingebettet werden. -
Sobald das JavaScript geladen ist, verwenden Sie
window.IframeCheckoutHandler(paymentMethodConfigurationId), um einen neuen Iframe-Checkout-Handler zu erstellen, wobeipaymentMethodConfigurationIddie ID der Zahlartenkonfiguration ist, wie sie von mögliche Zahlarten abrufen zurückgegeben wird. Dieser Handler kann verwendet werden, um das Iframe zu laden. Um das Iframe zu laden, rufen Siecreate(containerId)auf, wobeicontainerIddie ID des HTML-Elements ist, in das das Iframe eingebettet werden soll. Es wird empfohlen, vor dem Erstellen des Iframes einenvalidationCallbackzu registrieren, der immer dann aufgerufen wird, wenn die Validierung auf dem im Iframe geladenen Formular ausgelöst wird. DervalidationCallbackwird auf dem Handler mit der MethodesetValidationCallback(validationCallback)gesetzt. Der Callback sollte verwendet werden, um die als Argument übergebenen Fehlermeldungen anzuzeigen. -
Es ist möglich, vor dem Erstellen des Iframes zusätzliche und optionale Callbacks auf dem Handler zu registrieren. Mit dem
initializeCallbackkann ein Handler registriert werden, der nach der Initialisierung des Iframes aufgerufen wird. DerheightChangeCallbackwird jedes Mal aufgerufen, wenn sich die Höhe des Iframes ändert. Das Callback-Argument ist die Höhe in Pixeln. Die Callbacks werden mit der MethodesetInitializeCallback(initializeCallback)bzw.setHeightChangeCallback(heightChangeCallback)gesetzt. -
Fügen Sie eine Schaltfläche hinzu, die die Validierung des Formulars im Iframe auslöst. Um die Validierung auszulösen, rufen Sie die Methode
validate()auf dem Iframe-Checkout-Handler auf. Sie können das Iframe ausblenden, wenn die Validierung ohne Fehler abgeschlossen wurde. Entfernen Sie das Iframe nicht. Die im Frame gespeicherten Daten werden später verwendet. -
Sobald das Formular validiert ist und die Transaktion abgeschlossen werden soll, erstellen Sie eine Bestellung in Ihrer Anwendung und bestätigen Sie die Transaktion mit der Methode
confirmauf demTransaction Service. Sie sollten dafür einen Ajax-Aufruf verwenden, da sonst das Iframe neu geladen wird und alle Daten verloren gehen. Sie können die Transaktion auch aktualisieren, bevor Sie sie bestätigen. Z.B. können Sie abhängig von der gewählten Zahlart zusätzliche Gebühren anwenden oder die Versandkosten oder die Lieferadresse ändern. -
Nun sollte die Methode
submit()auf dem Iframe-Checkout-Handler aufgerufen werden. Dies führt dazu, dass das Formular im Iframe abgeschickt wird und aus dem Iframe ausbricht, d.h. die Händler-Website verlassen wird. Der Kunde wird unter Umständen aufgefordert, zusätzliche Informationen einzugeben. Dies hängt von der Zahlart ab. -
Wenn die Transaktion auf unserer Seite
authorizedoderfailedist, wird der Kunde auf diesuccessUrloderfailedUrlweitergeleitet, die beim Erstellen des Transaktionsobjekts definiert wurde. -
Warten Sie auf die Benachrichtigung an der definierten Webhook-URL, um die Bestellung im Händlersystem als
authorizedoderfailedzu markieren. Dieser Benachrichtigungs-Listener ist wichtig, da der Kunde das Fenster schliessen könnte, bevor er zur Händleranwendung zurückkehrt. Der Status der Transaktion kann jederzeit über die API abgerufen werden.
Einige Zahlarten erfordern einen komplexeren Prozess in mehreren Schritten. Standardmässig ist im Zahlungsformular eine Schaltfläche enthalten, um durch diese Schritte zu navigieren. Es ist jedoch möglich, diese Schaltflächen auszublenden und die primäre Absenden-Schaltfläche in Ihrer Anwendung zu verwenden, um die Ereignisse auszulösen.
Um die ersetzten primären Aktionen zu verarbeiten, registrieren Sie mit setReplacePrimaryActionCallback(callback) einen Callback auf dem Iframe-Handler. Dieser Callback wird mit der neuen Beschriftung als Parameter aufgerufen, mit der die primäre Schaltfläche aktualisiert werden soll, wann immer die primäre Aktion ersetzt wird. Zusätzlich muss die Schaltfläche so geändert werden, dass sie die Aktion trigger() auslöst.
Wenn der Kunde alle notwendigen Schritte erfolgreich durchlaufen hat, wird der mit setResetPrimaryActionCallback(callback) registrierte Callback aufgerufen, was dazu führen sollte, dass die primäre Schaltfläche auf das Standardverhalten zurückgesetzt wird, d.h. die ursprüngliche Beschriftung hat und die Aktionen validate() und submit() auslöst.
Um die Schaltflächen im Zahlungsformular auszublenden, setzen Sie die Konfiguration entsprechend, bevor Sie den Iframe-Checkout-Handler erstellen:
window.IframeCheckoutHandler.configure('replacePrimaryAction', true);Die oben beschriebenen Schritte sollen nun etwas detaillierter erklärt werden, einschliesslich der API-Operationen mit Beispiel-Requests.
Die Zahlungsannahme über iFrame bietet eine nahtlose Möglichkeit, Zahlungsinformationen von Ihrem 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 zu halten, und erreicht dennoch einen vollständig integrierten Checkout-Ablauf.
Nachfolgend sehen Sie ein Beispiel für ein client-seitiges Setup, bei dem das Iframe über die JavaScript-Ressource platziert wird, die von der Plattform bereitgestellt wird. Wie die { JavaScript URL } aufgelöst werden kann, wo die paymentMethodConfigurationId abgerufen werden kann usw., wird in den Beispielen weiter unten gezeigt.
<ul id="payment-errors"></ul>
<div id="payment-form"></div>
<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;
// Set here the id of the HTML element the payment iframe should be appended to.
var containerId = 'payment-form';
var handler = window.IframeCheckoutHandler(paymentMethodConfigurationId);
handler.setValidationCallback(
function(validationResult){
// Reset payment errors
$('#payment-errors').html('');
if (validationResult.success) {
// Create the order within the shop and eventually update the transaction.
$.ajax('http://your-shop-backend.com/create-order', {
success: function(){
handler.submit();
}
});
} else {
// Display errors to customer
$.each(validationResult.errors, function(index, errorMessage){
$('#payment-errors').append('<li>' + errorMessage + '</li>');
});
}
});
//Set the optional initialize callback
handler.setInitializeCallback(function(){
//Execute initialize code
});
//Set the optional height change callback
handler.setHeightChangeCallback(function(height){
//Execute code
});
handler.create(containerId)
$('#pay-button').on('click', function(){
handler.validate();
});
</script>Um ein Transaktionsobjekt zu erstellen, müssen Sie die
Transaction-Create-Operation verwenden.
Hier geben Sie die Kundendaten an, die Sie haben, einschliesslich der Positionen und Preise.
Dadurch wird eine Transaktion im Status pending in Ihrem Space erstellt.
|
Note
|
Es wird empfohlen, alle Informationen anzugeben, die Sie vom Käufer haben. 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@wallee.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 Beispiel unten 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
}Um die URL zum JavaScript zu erhalten, können Sie die Operation buildJavaScriptUrl verwenden, um eine URL zu erhalten, die auf das
JavaScript verweist, das in Ihren Checkout eingebunden werden sollte, um das Iframe zu erstellen. Fügen Sie das JavaScript auf Ihrer
Seite ein, wo das Iframe angezeigt werden soll, wie im client-seitigen Beispiel oben gezeigt.
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,
"linkedSpaceId": 396,
"name": "Credit / Debit Card",
"oneClickPaymentMode": "ALLOW",
"paymentMethod": {
"id": 1457546097597
},
"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
}Transaktionseigenschaften können aktualisiert werden, solange sich die Transaktion nicht im Status confirmed befindet. Um
dies zu tun, verwenden Sie die Operation update auf dem Transaction Service.
|
Note
|
Werfen Sie einen Blick auf den Abschnitt Objektversionierung / Sperrung,
der beschreibt, wie Sie mit der Eigenschaft version umgehen müssen, um Probleme mit dem optimistischen Locking zu vermeiden.
|
Anfrage
Im folgenden 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
}Falls die Eigenschaft für die automatische Bestätigung 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 erfolgen, sobald die Eingaben des Kunden validiert wurden und
die ausstehende Bestellung in Ihrer Anwendung erstellt ist (siehe Schritt 7 im Prozess oben).
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
}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 über Webhooks, Webhook-Listener und deren Konfiguration finden Sie in der Webhooks-Dokumentation.
Wenn im Shop Content-Security-Policy-Einschränkungen angewendet werden, müssen für https://staging-wallee.com die folgenden Einschränkungen 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 Direktive CSP: script-src so gesetzt wird, dass das Laden von https://staging-wallee.com-URLs als gültige Quellen für JavaScript erlaubt ist, die Richtlinie Unsafe inline script Inline-Skript-Ausführungen erlaubt, die Direktive CSP: frame-src das Laden von https://staging-wallee.com-URLs über Iframe-Schnittstellen erlaubt und die Direktive CSP: connect-src 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;