Skip to main content
Mit dem $wsCheckout-Modul lesen Sie alle Daten des Bestellvorgangs im Frontend aus. Darunter die gewählte Zahlungs- und Versandart, Rechnungs- und Lieferadresse, die Bestellsummen sowie den Validierungs- und Fehlerstatus. Auf dieser Seite geht es um das Lesen der Checkout-Daten. Alles, was den Checkout verändert (Adresse wählen, Zahlungsart setzen, Bestellung auslösen), ist unter Aktionen → Checkout beschrieben.

Grundkonzept

Der Checkout sammelt die Auswahl des Kunden (Zahlung, Versand, Adressen, Freifelder) und prüft fortlaufend, ob die Bestellung ausführbar ist. Über $wsCheckout lesen Sie diese Auswahl und den Prüfstatus, um den Bestellablauf zu gestalten und dem Kunden gezielt Rückmeldung zu geben.

Validierung

Für das Prüf-Feedback gibt es drei Ebenen, die unterschiedlich genau sind. Wählen Sie die Ebene nach dem, was Sie anzeigen wollen:
  • Gesamtstatus - isValid gibt an, ob die Bestellung insgesamt ausführbar ist. Nutzen Sie es beispielsweise, um den „Kaufen”-Button freizugeben oder zu sperren.
  • Feldzustand - fieldStates liefert pro Feld einen Zustand (untouched, empty, invalid, incompatible, valid). Nutzen Sie es beispielsweise, um ein Feld optisch zu markieren.
  • Konkrete Fehler - problems liefert je Bereich eine Liste von Fehlern mit Fehler-Code und dem Namen des fehlgeschlagenen Checks. Nutzen Sie es beispielsweise, um dem Kunden zu sagen, wie der Fehler konkret zu lösen ist.

Sofort-Fehler und Fehler nach einer Aktion

Der Checkout kennt zwei Quellen für Fehler-Feedback:
  • $wsCheckout.problems.* - wird angezeigt, sobald ein Feld angewählt bzw. verlassen wurde, sofern show*BeforeSubmit in der Konfiguration auf true steht. Nach dem ersten Kaufversuch werden die Fehler unabhängig von dieser Einstellung angezeigt.
  • actionResponse-Fehler - stammen aus der Server-Antwort nach einer Aktion. Für die meisten Sektionen werden sie ungefiltert ausgegeben. Ausnahme: Bei Kundendatenfeldern und der Draft-Adresse gibt es kein problems.*, dort werden die actionResponse-Fehler über show*BeforeSubmit gefiltert.

Auswahl-IDs und Draft-Adressen

Die selected*-Variablen enthalten die ID der jeweils gewählten Option (z. B. die Adress-ID, die Sie an $wsAccount.loadAddress() übergeben). Legt der Kunde im Bestellablauf eine neue Adresse an, die noch nicht im Kundenkonto gespeichert ist (Draft-Adresse), wird sie unter einer festen System-ID geführt: draftBillAddressId bzw. draftShippingAddressId. Diese IDs sind immer vorhanden - auch wenn kein Entwurf existiert. Ob tatsächlich ein Entwurf vorliegt (und welche Daten er enthält), lesen Sie über die Maps draftBillAddress / draftShippingAddress, die nur dann ausgegeben werden.

Modulübersicht

Beispiel / Ausschnitt über $wsCheckout
JSON-Ausgabe (gekürzt)
Anmerkung: "ƒ()" kennzeichnet eine Funktion. Konditionale Variablen wie orderId, orderCreatedAt, restUntilFreeDelivery, freeShippingMethod, draftBillAddress und draftShippingAddress erscheinen nur, wenn sie gesetzt sind. Variablen in der Übersicht Methoden in der Übersicht

Templates

Der Checkout ist frei gestaltbar und kann eine oder mehrere Shopseiten umfassen. Die Reihenfolge der Elemente ist beliebig.

Variablen

$wsCheckout.accountType

Gibt den Kontotyp aus: "guest" (Gast), "new" (neues Konto) oder "registered" (angemeldet). Solange der Kunde noch keinen Kontotyp gewählt hat, ist der Wert leer (""). Werten Sie ihn aus, um beispielsweise einem Gast die Konto-Erstellung anzubieten.

$wsCheckout.guestMail

Gibt die E-Mail-Adresse eines Gastkontos aus. Nur bei einer Gastbestellung gefüllt.

$wsCheckout.selectedPayment / selectedShippingMethod

Geben die ID der gewählten Zahlungs- bzw. Versandart aus. Werten Sie sie aus, um die getroffene Auswahl anzuzeigen oder zu prüfen.

$wsCheckout.selectedBillAddress / selectedShippingAddress

Geben die ID der gewählten Rechnungs- bzw. Lieferadresse aus. Diese ID übergeben Sie z. B. an $wsAccount.loadAddress(), um die vollständige Adresse zu laden.

$wsCheckout.draftBillAddressId / draftShippingAddressId

Geben die feste System-ID aus, unter der eine im Bestellablauf neu angelegte, noch nicht im Kundenkonto gespeicherte Adresse (Draft-Adresse) geführt wird - z. B. um sie in der Adressauswahl als gewählte Adresse zu erkennen. Beide IDs sind immer vorhanden, unabhängig davon, ob ein Entwurf existiert. Ob tatsächlich ein Entwurf vorliegt, prüfen Sie über die Maps draftBillAddress / draftShippingAddress.

$wsCheckout.draftBillAddress / draftShippingAddress

Geben die Daten der Draft-Rechnungs- bzw. Draft-Lieferadresse als Map aus. Nur vorhanden, wenn ein Entwurf existiert - damit eignen sie sich auch als Existenz-Prüfung. Die Keys entsprechen den Adressfeldnamen (Standardfelder wie firstName, lastName, street, zip, city, country sowie zusätzliche Adressfelder). Ausgegeben werden nur Felder mit nicht-leerem Wert.
Eine Draft-Adresse wird über die Aktion CheckoutSetDraftAddress angelegt.

$wsCheckout.useAlternativeShippingAddress

Gibt aus, ob eine von der Rechnungsadresse abweichende Lieferadresse verwendet wird.

$wsCheckout.selectedStoreId

Gibt die ID der gewählten Filiale aus (z. B. für Click & Collect). 0, wenn keine Filiale gewählt ist.

$wsCheckout.selectedPseudoCC

Gibt den Pseudo-Kreditkarten-Token der gewählten Zahlung aus.

$wsCheckout.orderId / orderCreatedAt

Geben die ID und den Erstellzeitpunkt (ISO 8601) der Bestellung aus. Beide Variablen sind nur vorhanden, sobald in der aktuellen Session eine Bestellung existiert - z. B. auf der Bestellbestätigungsseite.

$wsCheckout.customerData

Gibt die konfigurierten Kundendaten-Felder aus - gruppiert und nach Zielgruppe aufgeteilt. Welche Felder enthalten sind, hängt vom Login-Status ab: Bei eingeloggten Kunden die Kontofelder, sonst die in der Bestellung gespeicherten Felder.

Struktur von $wsCheckout.customerData

Gruppen-Objekt

Die Gruppen entsprechen der Konfiguration unter customer.customerDataGroup.

Feld-Objekt

Beispiel, das alle sichtbaren Feldgruppen mit ihren Feldern ausgibt:

$wsCheckout.freeFields

Gibt die freien Checkout-Felder aus (z. B. AGB-Checkbox, Kommentarfeld). Iterieren Sie über die Felder und werten Sie sie über ihre id aus.

Eigenschaften eines freien Feldes

$wsCheckout.isValid

Gibt aus, ob die Bestellung insgesamt ausführbar ist. Dies ist der Gesamtstatus über alle Felder – nutzen Sie ihn, um den „Kaufen”-Button frei- oder zu sperren.

$wsCheckout.isExpressCheckoutLocked

Gibt aus, ob der Express-Checkout gesperrt ist – z. B. nachdem der Kunde über PayPal bezahlt hat und zur Bestätigung in den Shop zurückgeleitet wird. Werten Sie es aus, um in diesem Zustand das Bearbeiten des Warenkorbs zu unterbinden.

$wsCheckout.isPPCExpressCheckout / isPPCApplePayExpressCheckout / isPPCGooglePayExpressCheckout

Geben aus, ob der jeweilige Express-Checkout der PayPal Commerce Platform aktiv ist. Nutzen Sie sie, um den passenden Express-Checkout-Ablauf darzustellen.

$wsCheckout.paymentCaptchaRequired / paymentBlocked

Schutz vor wiederholten Zahlungsversuchen (IP- oder Session-basiert): paymentCaptchaRequired gibt aus, ob vor dem nächsten Zahlungsversuch ein Captcha gelöst werden muss. paymentBlocked gibt aus, ob weitere Zahlungsversuche aktuell blockiert sind.

$wsCheckout.isOrderBlockedByIneffectiveVoucher

Gibt aus, ob die Bestellung blockiert ist, weil ein eingelöster Gutschein im aktuellen Warenkorb keine Wirkung entfalten kann. Nutzen Sie es, um den Bestellbutton zu sperren.
Das Flag meldet nur den Zustand. Um dem Kunden den konkreten Grund und den betroffenen Gutschein zu nennen, werten Sie zusätzlich ineffectiveVoucherErrors aus. Ob die Bestellung überhaupt blockiert wird, steuert disableOrderOnIneffectiveVoucher in der Checkout-Konfiguration.

$wsCheckout.ineffectiveVoucherErrors

Gibt eine Liste der Fehler zu eingelösten Gutscheinen aus, die im aktuellen Warenkorb keine Wirkung entfalten. Jeder Eintrag nennt den Grund und, soweit zuordenbar, den betroffenen Gutschein. Damit ersetzen Sie einen allgemeinen Hinweis durch eine konkrete Aussage. Greifen alle Gutscheine, ist die Liste leer. Anders als bei problems enthalten diese Fehler bereits einen fertigen Text. Der Shop übersetzt dazu den Textbaustein, der im Konfigurationsknoten checkout.voucherErrors zum jeweiligen Fehlerfall hinterlegt ist.

Eigenschaften eines Fehlers

subCode und field sind vorhanden, damit alle Fehlerobjekte im Frontend denselben Aufbau haben. Sie werden hier derzeit nicht gefüllt, können aber später Werte erhalten. Werten Sie sie deshalb nur aus, wenn sie tatsächlich gefüllt sind.

Bedeutung der Fehler-Codes

Die Liste kann künftig weitere Codes enthalten. Sehen Sie im Template deshalb einen Fallback für unbekannte Codes vor, beispielsweise die Ausgabe von text.
details.voucherId ist nicht in jedem Fehler enthalten. Steht minOrderValueCalculation auf sum und wird erst die Summe aller Mindestbestellwerte nicht erreicht, gehört der Fehler zu keinem einzelnen Gutschein und kommt ohne ID. Prüfen Sie den Key deshalb immer, bevor Sie ihn ausgeben. Welcher Fehler wann entsteht, steht unter Wann welcher Fehler entsteht.
Beispiel, das je Gutschein den konkreten Grund ausgibt:
Ergebnis
Pro wirkungslosem Gutschein erscheint eine Zeile mit Gutschein-ID und Grund. Der Fehler aus der Summenprüfung erscheint als Zeile ohne ID.

$wsCheckout.verificationStatus / verificationStatusOptions

verificationStatus gibt den Verifizierungsstatus der Bestellung als Zahl aus. verificationStatusOptions listet den möglichen Status auf.

$wsCheckout.voucherAppliesPerItem

Gibt aus, ob ein Gutschein pro Artikel (statt auf den Gesamtbetrag) angewendet wird.

$wsCheckout.restUntilFreeDelivery / freeShippingMethod

restUntilFreeDelivery gibt den verbleibenden Betrag bis zur Grenze für kostenlosen Versand aus (0, wenn die Grenze erreicht ist). Die Variable ist nur vorhanden, wenn für den Warenkorb eine Gratisversand-Grenze ermittelbar ist. Nutzen Sie sie für einen Hinweis „Noch X bis zum kostenlosen Versand”. freeShippingMethod enthält zusätzlich die ID der konfigurierten Standard-Gratisversandart - aber nur, solange der Kunde noch keine Versandart gewählt hat und eine Standard-Gratisversandart konfiguriert ist.

$wsCheckout.fieldStates

Gibt eine Map mit dem Zustand jedes Checkout-Feldes aus (payment, shippingMethod, billAddress, shippingAddress). Damit markieren Sie einzelne Felder gezielt – z. B. ein noch nicht ausgefülltes Feld neutral, ein fehlerhaftes rot.
Die Zustände bauen aufeinander auf. Geprüft wird der Reihe nach: angewählt (untouched) → Wert vorhanden (empty) → gültig (invalid) → im Kontext zulässig (incompatible). Erst wenn alle Prüfungen bestanden sind, gilt das Feld als valid. Der erste zutreffende Zustand wird ausgegeben.

$wsCheckout.problems

Gibt eine Map mit konkreten Fehlern je Bereich aus. Die Map enthält genau sechs Bereiche: payment, shippingMethod, billAddress, shippingAddress, clearing und general. Jeder Bereich ist eine Liste von Fehlern; sie ist gefüllt, wenn dort ein Problem vorliegt.

Eigenschaften eines Fehlers

Jeder Fehler ist ein Objekt mit genau zwei Eigenschaften:
Einen sprechenden Fehlertext (text) oder das betroffene Feld (field) enthalten die Fehler-Objekte nicht. Formulieren Sie die Kundenmeldung im Template anhand von code und ggf. check (siehe Beispiel unten).

Bedeutung der Fehler-Codes

Beispiel, das die Fehler der Zahlungsart kundenfreundlich ausgibt:
Um auf einen einzelnen Fehler zuzugreifen, verwenden Sie den Index, z. B. $wsCheckout.problems.payment[0].code. Fehler zu freien Checkout-Feldern liefert $wsCheckout.problems nicht - diese werten Sie über die actionResponse-Fehler der jeweiligen Aktion aus (z. B. CheckoutSetFreeFields).

$wsCheckout.sum

Gibt eine Map mit den Preisinformationen zum Checkout aus. Für die Anzeige als Geldbetrag verwenden Sie den currency-Filter – er enthält bereits das Währungssymbol.

Eigenschaften von $wsCheckout.sum


Methoden

$wsCheckout.isValidPayment()

Prüft, ob die Zahlungsart mit der angegebenen ID verfügbar ist. Dabei werden alle Validierungsregeln ausgeführt, die in der Konfiguration der Zahlungsart unter validations hinterlegt sind (siehe paymentValidation.* - Zahlungsarten-Validierung) - z.B. Länderregeln, Bestellwertgrenzen oder der Ausschluss bei Gutscheinprodukten im Warenkorb (paymentValidation.voucherDeny). Zusätzlich wird geprüft, ob die Zahlungsart aktiv und für das Kundenkonto zugelassen ist. Schlägt mindestens eine Regel fehl, gibt die Methode false zurück. Auf diese Weise wirken die konfigurierten Validierungsregeln im Frontend: Das Template blendet die Zahlungsart aus oder deaktiviert sie. Signatur
$wsCheckout.isValidPayment(paymentId)
Rückgabe
true / false - Zahlungsart verfügbar / nicht verfügbar.
Parameter Beispiel, das prüft, ob die Zahlungsart verfügbar ist.
Beispiel, das alle Zahlungsarten als Auswahl anbietet und nicht verfügbare Zahlungsarten deaktiviert. Zahlungsarten, deren Validierung fehlschlägt (z.B. wegen paymentValidation.voucherDeny bei einem Gutscheinprodukt im Warenkorb), sind sichtbar, aber nicht wählbar.
Warum die aktuell ausgewählte Zahlungsart ungültig ist, lässt sich über $wsCheckout.problems.payment auswerten; das Feld check enthält dort den Namen des fehlgeschlagenen Validierungsservices.

$wsCheckout.isValidShippingMethod()

Prüft, ob die Versandart mit der angegebenen ID verfügbar ist. Dabei werden alle Validierungsregeln ausgeführt, die in der Konfiguration der Versandart unter validations hinterlegt sind (siehe shippingMethodValidation.* - Versandarten-Validierung) - z.B. Länderregeln, Warenwertgrenzen oder Produkttyp-Beschränkungen. Schlägt mindestens eine Regel fehl, gibt die Methode false zurück. Das Template blendet die Versandart dann aus oder deaktiviert sie (gleiches Muster wie bei isValidPayment()). Die Gründe für eine deaktivierte Versandart lassen sich über getShippingMethodDisabledErrors() ausgeben. Signatur
$wsCheckout.isValidShippingMethod(shippingMethodId)
Rückgabe
true / false - Versandart verfügbar / nicht verfügbar.
Parameter Beispiel, das prüft, ob die angegebene Versandart verfügbar ist.

$wsCheckout.isValidBillAddress() / isValidShippingAddress()

Prüfen, ob die Adresse mit der angegebenen ID als Rechnungs- bzw. Lieferadresse gültig ist. Signatur
$wsCheckout.isValidBillAddress(addressId) · $wsCheckout.isValidShippingAddress(addressId)
Rückgabe
bool – gültig / nicht gültig.

$wsCheckout.isPending() / isFinished()

isPending() prüft, ob ein Zahlungsvorgang noch aussteht, isFinished(), ob die Bestellung abgeschlossen wurde. Nutzen Sie sie, um den Status einer laufenden oder abgeschlossenen Bestellung zu erkennen. Signatur
$wsCheckout.isPending() · $wsCheckout.isFinished()
Rückgabe
bool.

$wsCheckout.getAmountInSmallestUnit()

Gibt einen Betrag in der kleinsten Währungseinheit zurück (z. B. Cent statt Euro). Nützlich für Zahlungs-APIs, die Beträge in Cent erwarten. Signatur
$wsCheckout.getAmountInSmallestUnit(amount)
Rückgabe
int – Betrag in kleinster Einheit.

$wsCheckout.getShippingMethodDisabledErrors()

Gibt zurück, warum eine Versandart deaktiviert ist. Nutzen Sie es, um dem Kunden zu erklären, weshalb eine Versandart nicht wählbar ist. Signatur
$wsCheckout.getShippingMethodDisabledErrors(shippingMethodId)
Rückgabe
array – Liste mit Fehlermeldungen.

$wsCheckout.getShippingCost()

Gibt die Versandkosten einer bestimmten Versandart zurück. Auch dann, wenn diese nicht ausgewählt ist. Der Wert bezieht sich auf den aktuellen Warenkorb. Nutzen Sie es beispielsweise, um die Versandkosten verschiedener Optionen vorab anzuzeigen. Signatur
$wsCheckout.getShippingCost(shippingMethodId)
Rückgabe
float – Versandkosten der angegebenen Versandart.

$wsCheckout.itemVoucherDiscount()

Berechnet den Gutscheinrabatt für einen einzelnen Warenkorb-Artikel. Übergeben Sie die ID eines Warenkorb-Eintrags. Signatur
$wsCheckout.itemVoucherDiscount(itemId)
Rückgabe
float – Rabattbetrag für den Artikel.

Aktionen

Aktionen, die den Checkout verändern (Adresse wählen, Zahlungsart setzen, Bestellung auslösen), sind separat dokumentiert: Aktionen → Checkout.

Beispiele

Bestellbarkeit prüfen und Fehler anzeigen

Dieses Beispiel kombiniert die Validierungsebenen:
Ist die Bestellung gültig, wird der „Kaufen”-Bereich angezeigt, sonst werden die konkreten Probleme aufgelistet - anhand von code und check, da die Fehler-Objekte keinen fertigen Text enthalten.
Ergebnis
Bei gültiger Bestellung erscheint der Kaufen-Bereich, sonst die offenen Punkte je Bereich.

Summenübersicht

Eine vollständige Summenanzeige. Der currency-Filter enthält das Währungssymbol bereits.
Ergebnis
Eine aufgeschlüsselte Summenübersicht mit korrekt formatierten Geldbeträgen.

AGB-Zustimmung prüfen

Prüft, ob das Freifeld agb angehakt ist, bevor die Bestellung erlaubt wird.
Ergebnis
Ist die AGB-Checkbox nicht angehakt, erscheint der Hinweis.

Gewählte Zahlungsart prüfen

Ergebnis
Die gewählte Zahlungsart wird angezeigt, sofern sie gültig ist.

  • Aktionen → Checkout – den Checkout verändern (Auswahl setzen, Bestellung auslösen), weil $wsCheckout selbst nur liest.
  • $wsBasket – der Warenkorb, auf dem der Checkout aufbaut; liefert die Artikel für itemVoucherDiscount().
  • $wsAccount – lädt über loadAddress() die vollständige Adresse zur selectedBillAddress/selectedShippingAddress.
  • Checkout-Konfiguration – steuert mit show*BeforeSubmit, wann Fehler angezeigt werden.
  • Fehlertexte zu wirkungslosen Gutscheinen – pflegt die Texte, die ineffectiveVoucherErrors ausgibt.
  • $wsVoucher – die eingelösten Gutscheine selbst, passend zu den IDs aus ineffectiveVoucherErrors.