$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 -
isValidgibt an, ob die Bestellung insgesamt ausführbar ist. Nutzen Sie es beispielsweise, um den „Kaufen”-Button freizugeben oder zu sperren. - Feldzustand -
fieldStatesliefert pro Feld einen Zustand (untouched,empty,invalid,incompatible,valid). Nutzen Sie es beispielsweise, um ein Feld optisch zu markieren. - Konkrete Fehler -
problemsliefert 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, sofernshow*BeforeSubmitin der Konfiguration auftruesteht. 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 keinproblems.*, dort werden dieactionResponse-Fehler übershow*BeforeSubmitgefiltert.
Auswahl-IDs und Draft-Adressen
Dieselected*-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
"ƒ()" 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 MapsdraftBillAddress / 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 wiefirstName, lastName, street, zip, city, country sowie zusätzliche Adressfelder). Ausgegeben werden nur Felder mit nicht-leerem Wert.
$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 untercustomer.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 ihreid 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.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 beiproblems 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.
Beispiel, das je Gutschein den konkreten Grund ausgibt:
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: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 dencurrency-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 untervalidations 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ückgabetrue / false - Zahlungsart verfügbar / nicht verfügbar.
Parameter
Beispiel, das prüft, ob die Zahlungsart verfügbar ist.
paymentValidation.voucherDeny bei einem Gutscheinprodukt im Warenkorb), sind sichtbar, aber nicht wählbar.
$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 untervalidations 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ückgabetrue / 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ückgabebool – 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ückgabebool.
$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ückgabeint – 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ückgabearray – 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ückgabefloat – 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ückgabefloat – 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.
Bei gültiger Bestellung erscheint der Kaufen-Bereich, sonst die offenen Punkte je Bereich.
Summenübersicht
Eine vollständige Summenanzeige. Dercurrency-Filter enthält das Währungssymbol bereits.
Eine aufgeschlüsselte Summenübersicht mit korrekt formatierten Geldbeträgen.
AGB-Zustimmung prüfen
Prüft, ob das Freifeldagb angehakt ist, bevor die Bestellung erlaubt wird.
Ist die AGB-Checkbox nicht angehakt, erscheint der Hinweis.
Gewählte Zahlungsart prüfen
Die gewählte Zahlungsart wird angezeigt, sofern sie gültig ist.
Weiterführende Links
- Aktionen → Checkout – den Checkout verändern (Auswahl setzen, Bestellung auslösen), weil
$wsCheckoutselbst 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 zurselectedBillAddress/selectedShippingAddress. - Checkout-Konfiguration – steuert mit
show*BeforeSubmit, wann Fehler angezeigt werden. - Fehlertexte zu wirkungslosen Gutscheinen – pflegt die Texte, die
ineffectiveVoucherErrorsausgibt. - $wsVoucher – die eingelösten Gutscheine selbst, passend zu den IDs aus
ineffectiveVoucherErrors.
