$wsCheckout - Checkout - WEBSALE Dokumentation

With the $wsCheckout module, you read all data of the order process in the frontend. This includes the selected payment and shipping method, billing and shipping address, order totals, and the validation and error status. This page is about reading the checkout data. Everything that changes the checkout (choose an address, set a payment method, place the order) is described under Actions → Checkout.

Basic concept

The checkout collects the customer’s choices (payment, shipping, addresses, free fields) and continuously checks whether the order can be placed. Via $wsCheckout, you read this selection and the check status to shape the order flow and give the customer targeted feedback.

Validation

For the check feedback there are three levels with different granularity. Choose the level according to what you want to display:

Overall status - isValid indicates whether the order can be placed overall. Use it, for example, to enable or disable the “Buy” button.
Field state - fieldStates returns a state per field (untouched, empty, invalid, incompatible, valid). Use it, for example, to visually mark a field.
Concrete errors - problems returns a list of errors per area with an error code and the name of the failed check. Use it, for example, to tell the customer how to specifically resolve the error.

Immediate errors and errors after an action

The checkout knows two sources of error feedback:

$wsCheckout.problems.* - is displayed as soon as a field is selected or left, provided that show*BeforeSubmit is set to true in the configuration. After the first purchase attempt, the errors are displayed regardless of this setting.
actionResponse errors - come from the server response after an action. For most sections they are output unfiltered. Exception: for customer data fields and the draft address there is no problems.*; there, the actionResponse errors are filtered via show*BeforeSubmit.

Selection IDs and draft addresses

The selected* variables contain the ID of the currently chosen option (e.g. the address ID that you pass to $wsAccount.loadAddress()). If the customer creates a new address during the order flow that is not yet saved in the customer account (draft address), it is tracked under a fixed system ID: draftBillAddressId or draftShippingAddressId. These IDs are always present - even if no draft exists. Whether a draft actually exists (and which data it contains) is read via the maps draftBillAddress / draftShippingAddress, which are only output when this is the case.

Module overview

Example / excerpt of $wsCheckout

{{= $wsCheckout | json }}

JSON output (shortened)

{
  "accountType": "...",
  "customerData": { },
  "draftBillAddressId": "...",
  "draftShippingAddressId": "...",
  "fieldStates": { },
  "freeFields": [...],
  "guestMail": "...",
  "ineffectiveVoucherErrors": [...],
  "isExpressCheckoutLocked": false,
  "isOrderBlockedByIneffectiveVoucher": false,
  "isPPCApplePayExpressCheckout": false,
  "isPPCExpressCheckout": false,
  "isPPCGooglePayExpressCheckout": false,
  "isValid": false,
  "paymentBlocked": false,
  "paymentCaptchaRequired": false,
  "paymentMethodAutoReset": false,
  "problems": {
    "billAddress": [...],
    "clearing": [...],
    "general": [...],
    "payment": [...],
    "shippingAddress": [...],
    "shippingMethod": [...]
  },
  "selectedBillAddress": "...",
  "selectedPayment": "...",
  "selectedPseudoCC": "...",
  "selectedShippingAddress": "...",
  "selectedShippingMethod": "...",
  "selectedStoreId": 0,
  "shippingMethodAutoReset": false,
  "sum": { },
  "useAlternativeShippingAddress": false,
  "verificationStatus": 0,
  "verificationStatusOptions": [...],
  "voucherAppliesPerItem": false,
  "getAmountInSmallestUnit": "ƒ()",
  "getShippingCost": "ƒ()",
  "getShippingMethodDisabledErrors": "ƒ()",
  "isFinished": "ƒ()",
  "isPending": "ƒ()",
  "isValidBillAddress": "ƒ()",
  "isValidPayment": "ƒ()",
  "hasPaymentVault": false,
  "isValidShippingAddress": "ƒ()",
  "isValidShippingMethod": "ƒ()",
  "itemVoucherDiscount": "ƒ()"
}

Note: "ƒ()" denotes a function. Conditional variables such as orderId, orderCreatedAt, restUntilFreeDelivery, freeShippingMethod, draftBillAddress, and draftShippingAddress only appear when they are set. Variables overview

Variable	Return type	Description
`accountType`	string	Account type: `"guest"`, `"new"`, or `"registered"`. Empty (`""`) as long as no account type has been chosen.
`customerData`	map	Customer data fields, grouped and split by target group (including `groupedFields`, `newCustomerFieldGroups`, `existingCustomerFieldGroups`; structure see below).
`freeFields`	array	Free checkout fields (structure see below).
`guestMail`	string	Email of a guest account.
`selectedPayment`	string	ID of the selected payment method.
`selectedShippingMethod`	string	ID of the selected shipping method.
`selectedBillAddress`	string	ID of the selected billing address.
`selectedShippingAddress`	string	ID of the selected shipping address.
`draftBillAddressId`	string	Fixed system ID under which a draft billing address is tracked. Always present.
`draftShippingAddressId`	string	Fixed system ID under which a draft shipping address is tracked. Always present.
`draftBillAddress`	map	Data of the draft billing address. Only present if a draft exists.
`draftShippingAddress`	map	Data of the draft shipping address. Only present if a draft exists.
`selectedPseudoCC`	string	Pseudo credit card token.
`selectedStoreId`	int	ID of the selected store (e.g. Click & Collect).
`useAlternativeShippingAddress`	bool	Whether a different shipping address is active.
`orderId`	string	ID of the order. Only present as soon as an order exists in the session.
`orderCreatedAt`	string	Creation time of the order (ISO 8601). Only present as soon as an order exists.
`shippingMethodAutoReset` (future feature)	bool	Indicates whether the shipping method was reset automatically because the previously selected shipping method became invalid due to a change in the order context (e.g. change of the shipping country). Whether reselection happens automatically is controlled by `prevSelectionInvalidAutoSelect`.
`paymentMethodAutoReset` (future feature)	bool	Indicates whether the payment method was reset automatically because the previously selected payment method became invalid due to a change in the order context (e.g. change of the shipping country). Whether reselection happens automatically is controlled by `prevSelectionInvalidAutoSelect`.
`isValid`	bool	Checks whether the order can be placed overall.
`isExpressCheckoutLocked`	bool	Checks whether the express checkout is locked (e.g. after a PayPal payment).
`isPPCExpressCheckout`	bool	Checks whether the PayPal Commerce Platform express checkout is active.
`isPPCApplePayExpressCheckout`	bool	Checks whether Apple Pay Express Checkout is active.
`isPPCGooglePayExpressCheckout`	bool	Checks whether Google Pay Express Checkout is active.
`problems`	map	Concrete errors per area (structure see below).
`fieldStates`	map	State per checkout field (values see below).
`sum`	map	Price information for the checkout (structure see below).
`verificationStatus`	int	Verification status of the order.
`verificationStatusOptions`	array	Available verification status options.
`voucherAppliesPerItem`	bool	Checks whether vouchers are applied per item.
`restUntilFreeDelivery`	float	Remaining amount up to the threshold for free shipping (`0` when reached). Only present if a free shipping threshold can be determined for the basket.
`freeShippingMethod`	string	ID of the default free shipping method. Only present when `restUntilFreeDelivery` is output, no shipping method is chosen yet, and a default free shipping method has been configured.
`isOrderBlockedByIneffectiveVoucher`	bool	Checks whether the order is blocked by an ineffective voucher.
`ineffectiveVoucherErrors`	array	Errors for redeemed vouchers that have no effect on the current basket. Empty when all vouchers apply.
`paymentBlocked`	bool	Checks whether payment is blocked (protection against repeated payment attempts, IP- or session-based).
`paymentCaptchaRequired`	bool	Checks whether a captcha is required for payment (protection against repeated payment attempts).

Methods overview

Method	Return type	Description
`isValidPayment()`	bool	Checks whether a payment method is available.
`hasPaymentVault()`	bool	Checks whether a link exists for the payment method chosen in the checkout.
`isValidShippingMethod()`	bool	Checks whether a shipping method is available.
`isValidBillAddress()`	bool	Checks whether an address is valid as a billing address.
`isValidShippingAddress()`	bool	Checks whether an address is valid as a shipping address.
`isPending()`	bool	Checks whether a payment process is pending.
`isFinished()`	bool	Checks whether an order has been completed.
`getAmountInSmallestUnit()`	int	Converts an amount to the smallest currency unit (e.g. cents).
`getShippingMethodDisabledErrors()`	array	Returns why a shipping method is disabled.
`getShippingCost()`	float	Shipping costs of a shipping method, based on the current basket.
`itemVoucherDiscount()`	float	Calculates the voucher discount for an item.

Templates

The checkout is freely designable and can span one or more shop pages. The order of elements is arbitrary.

Variables

$wsCheckout.accountType

Outputs the account type: "guest" (guest), "new" (new account), or "registered" (registered). As long as the customer has not chosen an account type, the value is empty (""). Evaluate it to, for example, offer a guest the option to create an account.

{{ if $wsCheckout.accountType == "guest" }}
  <!-- Guest order -->
{{ /if }}

$wsCheckout.guestMail

Outputs the email address of a guest account. Only filled for a guest order.

Email: {{= $wsCheckout.guestMail }}

$wsCheckout.selectedPayment / selectedShippingMethod

Output the ID of the selected payment or shipping method. Evaluate them to display or check the selection made.

{{ if $wsCheckout.selectedPayment == "stripe" }}
  <!-- Stripe is selected -->
{{ /if }}

$wsCheckout.selectedBillAddress / selectedShippingAddress

Output the ID of the selected billing or shipping address. Pass this ID, for example, to $wsAccount.loadAddress() to load the full address.

{{ var $billAddress = $wsAccount.loadAddress($wsCheckout.selectedBillAddress) }}
{{= $billAddress.firstName }} {{= $billAddress.lastName }}

$wsCheckout.draftBillAddressId / draftShippingAddressId

Output the fixed system ID under which a newly created address (draft address) is tracked in the order flow, which has not yet been saved in the customer account - e.g. to recognize it as the selected address in the address selection. Both IDs are always present, regardless of whether a draft exists. Whether a draft actually exists is checked via the maps draftBillAddress / draftShippingAddress.

{{ if $wsCheckout.selectedBillAddress == $wsCheckout.draftBillAddressId }}
  <!-- The newly created (still unsaved) billing address is selected -->
{{ /if }}

$wsCheckout.draftBillAddress / draftShippingAddress

Output the data of the draft billing or draft shipping address as a map. Only present if a draft exists - which means they also serve as an existence check. The keys correspond to the address field names (standard fields such as firstName, lastName, street, zip, city, country, as well as additional address fields). Only fields with a non-empty value are output.

{{ if $wsCheckout.draftBillAddress }}
  New billing address:
  {{= $wsCheckout.draftBillAddress.firstName }} {{= $wsCheckout.draftBillAddress.lastName }},
  {{= $wsCheckout.draftBillAddress.street }}, {{= $wsCheckout.draftBillAddress.zip }} {{= $wsCheckout.draftBillAddress.city }}
{{ /if }}

A draft address is created via the CheckoutSetDraftAddress action.

$wsCheckout.useAlternativeShippingAddress

Outputs whether a shipping address different from the billing address is used.

{{ if $wsCheckout.useAlternativeShippingAddress }}
  <!-- Alternative shipping address -->
{{ /if }}

$wsCheckout.selectedStoreId

Outputs the ID of the selected store (e.g. for Click & Collect). 0 if no store is selected.

{{ if $wsCheckout.selectedStoreId > 0 }}
  <!-- Store selected -->
{{ /if }}

$wsCheckout.selectedPseudoCC

Outputs the pseudo credit card token of the selected payment.

Token: {{= $wsCheckout.selectedPseudoCC }}

$wsCheckout.orderId / orderCreatedAt

Output the ID and the creation time (ISO 8601) of the order. Both variables are only present as soon as an order exists in the current session - e.g. on the order confirmation page.

{{ if $wsCheckout.orderId }}
  Your order number: {{= $wsCheckout.orderId }} (created: {{= $wsCheckout.orderCreatedAt }})
{{ /if }}

$wsCheckout.customerData

Outputs the configured customer data fields - grouped and split by target group. Which fields are included depends on the login status: for logged-in customers the account fields, otherwise the fields stored in the order.

Structure of `$wsCheckout.customerData`

Key	Type	Description
`groupedFields`	array	Field groups with their fields (structure see group object). Always present.
`newCustomerFieldGroups`	array	Field groups with the fields for new customer registration. Always present.
`existingCustomerFieldGroups`	array	Field groups with the fields for existing customer registration. Always present.
`ungroupedFields`	array	Fields without group assignment. Only present when `showUngroupedFields` is active in `customer.customerDataFieldSettings`.
`newCustomerFields`	array	Fields of the new customer registration as a flat list. Only present when `showUngroupedFields` is active.
`existingCustomerFields`	array	Fields of the existing customer registration as a flat list. Only present when `showUngroupedFields` is active.

Group object

The groups correspond to the configuration under customer.customerDataGroup.

Property	Type	Description
`name`	string	Technical name of the group.
`label`	string	Display name of the group.
`hidden`	bool	Whether the group should be hidden (among others `true` if it contains no visible fields).
`fields`	array	The fields of the group (structure see field object).

Field object

Property	Type	Description
`name`	string	Technical name of the field.
`label`	string	Display name of the field.
`type`	string	Field type (e.g. `text`, `number`, `date`, `checkbox`, `select`).
`association`	string	Storage location according to `storageStrategy` (account, order, or both).
`hidden`	bool	Whether the field should be hidden.
`readonly`	bool	Whether the field is read-only.
`touched`	bool	Whether the field has already been edited by the customer.
`required`	bool	Whether the field is a required field.
`value`	string/bool	Current value (bool for `checkbox`, otherwise string).
`externalId`	string	External identifier of the field. Only present if configured.
`unit`	map	Unit information. Only for `number` fields with a configured unit.
`options`	array	Selection options (`{value, label}`). Only for `select` fields.

Example that outputs all visible field groups with their fields:

{{ foreach $group in $wsCheckout.customerData.groupedFields }}
  {{ if not $group.hidden }}
    <fieldset>
      <legend>{{= $group.label }}</legend>
      {{ foreach $field in $group.fields }}
        {{ if not $field.hidden }}
          <label>{{= $field.label }}{{ if $field.required }} *{{ /if }}</label>
        {{ /if }}
      {{ /foreach }}
    </fieldset>
  {{ /if }}
{{ /foreach }}

$wsCheckout.freeFields

Outputs the free checkout fields (e.g. terms and conditions checkbox, comment field). Iterate over the fields and evaluate them via their id.

{{ foreach $field in $wsCheckout.freeFields }}
  {{= $field.name }} ({{= $field.type }}, required: {{= $field.required }})
{{ /foreach }}

Properties of a free field

Property	Return type	Description
`id`	string	ID of the field (e.g. `"agb"`, `"comment"`).
`name`	string	Display name of the field (e.g. `"Terms and Conditions"`).
`type`	string	Field type (`"checkbox"`, `"text"`).
`required`	bool	Whether the field is a required field.
`default`	bool/string	Default value (bool for checkbox, string for text field).
`checked`	bool	Whether the checkbox is checked (only for `type == "checkbox"`).
`text`	string	Currently entered text (only for `type == "text"` and only present if a value has been set).

$wsCheckout.isValid

Outputs whether the order can be placed overall. This is the overall status across all fields – use it to enable or disable the “Buy” button.

{{ if $wsCheckout.isValid }}
  <!-- Order can be placed -->
{{ /if }}

$wsCheckout.isExpressCheckoutLocked

Outputs whether the express checkout is locked – e.g. after the customer has paid via PayPal and is redirected back to the shop for confirmation. Evaluate it to prevent editing of the basket in this state.

{{ if $wsCheckout.isExpressCheckoutLocked }}
  Editing your basket is currently not possible.
{{ /if }}

$wsCheckout.isPPCExpressCheckout / isPPCApplePayExpressCheckout / isPPCGooglePayExpressCheckout

Output whether the respective express checkout of the PayPal Commerce Platform is active. Use them to render the appropriate express checkout flow.

{{ if $wsCheckout.isPPCExpressCheckout }}
  <!-- PayPal Express Checkout active -->
{{ /if }}

$wsCheckout.paymentCaptchaRequired / paymentBlocked

Protection against repeated payment attempts (IP- or session-based): paymentCaptchaRequired outputs whether a captcha must be solved before the next payment attempt. paymentBlocked outputs whether further payment attempts are currently blocked.

{{ if $wsCheckout.paymentBlocked }}
  Too many failed payment attempts. Please try again later.
{{ elseif $wsCheckout.paymentCaptchaRequired }}
  <!-- Show captcha -->
{{ /if }}

$wsCheckout.isOrderBlockedByIneffectiveVoucher

Outputs whether the order is blocked because a redeemed voucher cannot take effect on the current basket. Use it to disable the order button.

{{ if $wsCheckout.isOrderBlockedByIneffectiveVoucher }}
  A redeemed voucher cannot be applied to this basket.
{{ /if }}

The flag only reports the state. To tell the customer the specific reason and the affected voucher, additionally evaluate ineffectiveVoucherErrors. Whether the order is blocked at all is controlled by disableOrderOnIneffectiveVoucher in the checkout configuration.

$wsCheckout.ineffectiveVoucherErrors

Outputs a list of the errors for redeemed vouchers that have no effect on the current basket. Each entry names the reason and, where assignable, the affected voucher. With this you replace a generic notice with a concrete statement. If all vouchers apply, the list is empty. Unlike problems, these errors already contain a ready-made text. The shop translates the text snippet stored under the configuration node checkout.voucherErrors for the respective error case.

Properties of an error

Property	Return type	Description
`code`	string	Type of the error (values see table below).
`subCode`	string	Finer subdivision of the error. Currently always empty (`""`).
`field`	string	Affected input field. Currently always empty (`""`), because no input field is involved in this context.
`text`	string	Translated error text from `checkout.voucherErrors`.
`details`	map	Additional information about the error. Contains the key `voucherId` with the ID of the affected voucher, provided the error can be assigned to a single voucher.

subCode and field are present so that all error objects in the frontend have the same structure. They are not currently filled here, but may receive values later. Only evaluate them if they are actually filled.

Meaning of the error codes

Code	Meaning
`"noValidProducts"`	The voucher is not applicable to any item in the basket, for example because it only applies to certain products or categories or because no item is eligible for discount.
`"minOrderValueNotReached"`	The minimum order value for the voucher is not reached.

The list may contain additional codes in the future. Therefore, provide a fallback in the template for unknown codes, for example by outputting text.

details.voucherId is not included in every error. If minOrderValueCalculation is set to sum and the sum of all minimum order values is not reached, the error does not belong to any single voucher and comes without an ID. Therefore, always check the key before outputting it. Which error is created when is described under When which error is created.

Example that outputs the concrete reason per voucher:

{{ if $wsCheckout.isOrderBlockedByIneffectiveVoucher }}
  <div role="alert">
    <strong>Vouchers cannot be redeemed:</strong>
    <ul>
      {{ foreach $cError in $wsCheckout.ineffectiveVoucherErrors }}
        <li>
          {{ if $cError.details.voucherId }}
            Voucher <strong>{{= $cError.details.voucherId }}</strong>:
          {{ /if }}
          {{= $cError.text | ifNull($cError.code) }}
        </li>
      {{ /foreach }}
    </ul>
  </div>
{{ /if }}

Result
For each ineffective voucher, a line appears with the voucher ID and reason. The error from the sum check appears as a line without an ID.

$wsCheckout.verificationStatus / verificationStatusOptions

verificationStatus outputs the verification status of the order as a number. verificationStatusOptions lists the possible statuses.

{{ foreach $option in $wsCheckout.verificationStatusOptions }}
  {{= $option.id }}: {{= $option.name }}
{{ /foreach }}

$wsCheckout.voucherAppliesPerItem

Outputs whether a voucher is applied per item (rather than to the total amount).

{{ if $wsCheckout.voucherAppliesPerItem }}
  <!-- Voucher is calculated per item -->
{{ /if }}

$wsCheckout.restUntilFreeDelivery / freeShippingMethod

restUntilFreeDelivery outputs the remaining amount up to the threshold for free shipping (0 when the threshold is reached). The variable is only present if a free shipping threshold can be determined for the basket. Use it for a hint like “Only X more until free shipping”. freeShippingMethod additionally contains the ID of the configured default free shipping method - but only as long as the customer has not yet chosen a shipping method and a default free shipping method is configured.

{{ if $wsCheckout.restUntilFreeDelivery > 0 }}
  Only {{= $wsCheckout.restUntilFreeDelivery | currency }} more until free shipping!
{{ /if }}

$wsCheckout.fieldStates

Outputs a map with the state of each checkout field (payment, shippingMethod, billAddress, shippingAddress). With this, you mark individual fields specifically – e.g. an unfilled field neutrally, an erroneous one in red.

Value	Description
`"untouched"`	The field has not yet been edited or selected.
`"empty"`	The field was filled, but the value was removed again.
`"invalid"`	A value is present, but has not passed validation.
`"incompatible"`	The value is valid, but not allowed in the current context.
`"valid"`	The field is filled in correctly and has passed all checks.

The states build on each other. They are checked in order: selected (untouched) → value present (empty) → valid (invalid) → allowed in context (incompatible). Only when all checks have passed is the field considered valid. The first matching state is output.

{{ if $wsCheckout.fieldStates.payment == "valid" }}
  <!-- Payment method correctly selected -->
{{ /if }}

$wsCheckout.problems

Outputs a map with concrete errors per area. The map contains exactly six areas: payment, shippingMethod, billAddress, shippingAddress, clearing, and general. Each area is a list of errors; it is filled when there is a problem there.

Properties of an error

Each error is an object with exactly two properties:

Property	Return type	Description
`code`	string	Error code (see table below).
`check`	string	Name of the failed validation service (e.g. `"voucherDeny"`). For `code == "missing"`, `check` is `null`. In the `clearing` area, `check` contains the error message from the payment provider instead.

The error objects do not contain a descriptive error text (text) or the affected field (field). Formulate the customer message in the template based on code and, if applicable, check (see example below).

Meaning of the error codes

Code	Meaning	Example
`"missing"`	No value selected or entered.	No payment method selected.
`"checkFailed"`	A value is present but has not passed validation.	Invalid address; in `general`: invalid account type (`check` = `"accountType"`).
`"checkIncompatible"`	The value is valid, but not allowed in the current context.	Payment method blocked for the shipping country.
`"clearingFailed"`	Payment processing at the provider failed. Only in the `clearing` area; `check` contains the provider’s error message.	Payment declined by Computop.

Example that outputs the payment method errors in a customer-friendly way:

{{ foreach $prob in $wsCheckout.problems.payment }}
  {{ if $prob.code == "missing" }}
    Please select a payment method.
  {{ elseif $prob.code == "checkFailed" }}
    The selected payment method is invalid ({{= $prob.check }}).
  {{ elseif $prob.code == "checkIncompatible" }}
    The selected payment method is not available for your selection ({{= $prob.check }}).
  {{ /if }}
{{ /foreach }}

To access a single error, use the index, e.g. $wsCheckout.problems.payment[0].code. $wsCheckout.problems does not provide errors for free checkout fields - evaluate these via the actionResponse errors of the respective action (e.g. CheckoutSetFreeFields).

$wsCheckout.sum

Outputs a map with the price information for the checkout. To display as a monetary amount, use the currency filter – it already includes the currency symbol.

Properties of `$wsCheckout.sum`

Property	Return type	Description
`total`	float	Total amount of the order (incl. shipping, discounts, taxes).
`totalNet`	float	Net amount.
`totalGross`	float	Gross amount.
`totalTax`	float	Total VAT.
`totalPreDeduction`	float	Total amount before tax deduction.
`totalVoucher`	float	Value of the redeemed vouchers.
`totalWeight`	float	Total weight of the order.
`shippingCost`	float	Shipping costs.
`paymentCost`	float	Costs of the payment method.
`surchargeCost`	float	Additional costs / surcharges.
`currency`	string	Currency code (e.g. `"EUR"`).
`totalTaxDeduction`	float	Amount of the deducted tax (in case of tax exemption).
`isTaxExempt`	bool	Whether the order is tax exempt.
`usedExemptionRule`	string	Active tax check rule (e.g. `"shippingOnly"`).
`billingCountry`	string	Country code of the billing address.
`shippingCountry`	string	Country code of the shipping address.

Total amount: {{= $wsCheckout.sum.total | currency }}
Shipping costs: {{= $wsCheckout.sum.shippingCost | currency }}

Methods

$wsCheckout.isValidPayment()

Checks whether the payment method with the specified ID is available. All validation rules stored in the configuration of the payment method under validations are executed (see paymentValidation.* - payment method validation) - e.g. country rules, order value limits, or the exclusion for voucher products in the basket (paymentValidation.voucherDeny). Additionally, it is checked whether the payment method is active and allowed for the customer account. If at least one rule fails, the method returns false. In this way, the configured validation rules take effect in the frontend: the template hides the payment method or disables it. Signature
$wsCheckout.isValidPayment(paymentId) Returns
true / false - payment method available / not available. Parameters

Name	Type	Required	Description
`paymentId`	string	yes	ID of the payment method to check.

Example that checks whether the payment method is available.

{{ if $wsCheckout.isValidPayment("stripe") }}
  // Stripe is available
{{ /if }}

Example that offers all payment methods for selection and disables unavailable payment methods. Payment methods whose validation fails (e.g. due to paymentValidation.voucherDeny for a voucher product in the basket) are visible but not selectable.

{{ foreach $cPayment in $wsConfig.payments }}
  <input type="radio" name="paymentId" value="{{= $cPayment.id }}"
    {{ if $wsCheckout.selectedPayment == $cPayment.id }} checked{{ /if }}
    {{ if not $wsCheckout.isValidPayment($cPayment.id) }} disabled{{ /if }}>
  <label>{{= $cPayment.name }}</label>
{{ /foreach }}

Why the currently selected payment method is invalid can be evaluated via $wsCheckout.problems.payment; the check field there contains the name of the failed validation service.

$wsCheckout.hasPaymentVault()

Checks whether the logged-in customer has a link to the payment provider, based on the payment method currently chosen in the checkout. If a link exists, the order is paid directly via it and the customer does not have to go through the approval at the payment provider again. Use this method in the checkout to either display the stored payment source or to show the offer to link. The method returns false in all doubtful cases: if no payment method is selected, if the selected payment method does not support linking, or if the customer is not logged in. Signature
$wsCheckout.hasPaymentVault() Returns
true / false - link present / not present. Example that distinguishes between a stored link and new linking in the checkout.

{{ if $wsCheckout.hasPaymentVault() }}
  <!-- Order runs via the stored link -->
{{ else }}
  <input type="checkbox" name="initPaymentVault" value="y">
  <label>Link account for future orders</label>
{{ /if }}

For a check outside the checkout, for example on a page in the customer account where the link is managed, use the $wsAccount.hasPaymentVault() method. This method expects the payment method as a parameter.

$wsCheckout.isValidShippingMethod()

Checks whether the shipping method with the specified ID is available. All validation rules stored in the configuration of the shipping method under validations are executed (see shippingMethodValidation.* - shipping method validation) - e.g. country rules, order value limits, or product type restrictions. If at least one rule fails, the method returns false. The template then hides the shipping method or disables it (same pattern as for isValidPayment()). The reasons why a shipping method is disabled can be output via getShippingMethodDisabledErrors(). Signature
$wsCheckout.isValidShippingMethod(shippingMethodId) Returns
true / false - shipping method available / not available. Parameters

Name	Type	Required	Description
`shippingMethodId`	string	yes	ID of the shipping method to check.

Example that checks whether the specified shipping method is available.

{{ if $wsCheckout.isValidShippingMethod("dhl_standard") }}
  // DHL Standard is available
{{ /if }}

$wsCheckout.isValidBillAddress() / isValidShippingAddress()

Check whether the address with the specified ID is valid as a billing or shipping address. Signature
$wsCheckout.isValidBillAddress(addressId) · $wsCheckout.isValidShippingAddress(addressId) Returns
bool – valid / not valid.

Name	Type	Required	Description
`addressId`	string	yes	ID of the address to check.

{{ if $wsCheckout.isValidBillAddress($wsCheckout.selectedBillAddress) }}
  <!-- Billing address is valid -->
{{ /if }}

$wsCheckout.isPending() / isFinished()

isPending() checks whether a payment process is still pending, isFinished() whether the order has been completed. Use them to detect the status of an in-progress or completed order. Signature
$wsCheckout.isPending() · $wsCheckout.isFinished() Returns
bool.

{{ if $wsCheckout.isPending() }}
  <!-- Payment process is still running -->
{{ /if }}

$wsCheckout.getAmountInSmallestUnit()

Returns an amount in the smallest currency unit (e.g. cents instead of euros). Useful for payment APIs that expect amounts in cents. Signature
$wsCheckout.getAmountInSmallestUnit(amount) Returns
int – amount in the smallest unit.

Name	Type	Required	Description
`amount`	float	yes	Amount in the main currency.

{{ var $cents = $wsCheckout.getAmountInSmallestUnit($wsCheckout.sum.total) }}

$wsCheckout.getShippingMethodDisabledErrors()

Returns why a shipping method is disabled. Use it to explain to the customer why a shipping method is not selectable. Signature
$wsCheckout.getShippingMethodDisabledErrors(shippingMethodId) Returns
array – list of error messages.

Name	Type	Required	Description
`shippingMethodId`	string	yes	ID of the shipping method to check.

{{ foreach $error in $wsCheckout.getShippingMethodDisabledErrors("express") }}
  {{= $error }}
{{ /foreach }}

$wsCheckout.getShippingCost()

Returns the shipping costs of a specific shipping method. Also when it is not selected. The value refers to the current basket. Use it, for example, to display the shipping costs of various options in advance. Signature
$wsCheckout.getShippingCost(shippingMethodId) Returns
float – shipping costs of the specified shipping method.

Name	Type	Required	Description
`shippingMethodId`	string	yes	ID of the shipping method whose costs are determined.

Shipping costs: {{= $wsCheckout.getShippingCost("dhl_standard") | currency }}

$wsCheckout.itemVoucherDiscount()

Calculates the voucher discount for a single basket item. Pass the ID of a basket entry. Signature
$wsCheckout.itemVoucherDiscount(itemId) Returns
float – discount amount for the item.

Name	Type	Required	Description
`itemId`	string	yes	ID of the basket entry.

Discount: {{= $wsCheckout.itemVoucherDiscount($item.id) | currency }}

Actions

Actions that change the checkout (choose an address, set a payment method, place the order) are documented separately: Actions → Checkout.

Examples

Check whether the order can be placed and display errors

This example combines the validation levels:
If the order is valid, the “Buy” area is shown, otherwise the concrete problems are listed - based on code and check, since the error objects do not contain a ready-made text.

{{ if $wsCheckout.isValid }}
  <!-- Show Buy button -->
{{ else }}
  {{ foreach $prob in $wsCheckout.problems.payment }}
    {{ if $prob.code == "missing" }}
      Please select a payment method.
    {{ else }}
      The selected payment method is not available ({{= $prob.check }}).
    {{ /if }}
  {{ /foreach }}
  {{ foreach $prob in $wsCheckout.problems.shippingMethod }}
    {{ if $prob.code == "missing" }}
      Please select a shipping method.
    {{ else }}
      The selected shipping method is not available ({{= $prob.check }}).
    {{ /if }}
  {{ /foreach }}
  {{ foreach $prob in $wsCheckout.problems.billAddress }}
    Please check your billing address ({{= $prob.code }}).
  {{ /foreach }}
{{ /if }}

Result
For a valid order, the Buy area appears, otherwise the open items per area.

Totals overview

A complete totals display. The currency filter already includes the currency symbol.

Subtotal: {{= $wsCheckout.sum.totalNet | currency }}
Shipping costs: {{= $wsCheckout.sum.shippingCost | currency }}
VAT: {{= $wsCheckout.sum.totalTax | currency }}
{{ if $wsCheckout.sum.totalVoucher > 0 }}
  Voucher: {{= $wsCheckout.sum.totalVoucher | currency }}
{{ /if }}
Total amount: {{= $wsCheckout.sum.total | currency }}

Result
An itemized totals overview with correctly formatted monetary amounts.

Check acceptance of terms and conditions

Checks whether the free field agb is checked before the order is allowed.

{{ foreach $field in $wsCheckout.freeFields }}
  {{ if $field.id == "agb" and not $field.checked }}
    Please accept the terms and conditions.
  {{ /if }}
{{ /foreach }}

Result
If the terms checkbox is not checked, the notice appears.

Check the selected payment method

{{ if $wsCheckout.isValidPayment($wsCheckout.selectedPayment) }}
  Selected payment method: {{= $wsCheckout.selectedPayment }}
{{ /if }}

Result
The selected payment method is displayed, provided it is valid.

Further links

Actions → Checkout – change the checkout (set selection, place order), because $wsCheckout itself only reads.
$wsBasket – the basket that the checkout is built on; provides the items for itemVoucherDiscount().
$wsAccount – loads the full address for selectedBillAddress/selectedShippingAddress via loadAddress().
Checkout configuration – controls with show*BeforeSubmit when errors are displayed.
Error texts for ineffective vouchers – maintains the texts that ineffectiveVoucherErrors outputs.
$wsVoucher – the redeemed vouchers themselves, matching the IDs from ineffectiveVoucherErrors.

​Basic concept

​Validation

​Immediate errors and errors after an action

​Selection IDs and draft addresses

​Module overview

​Templates

​Variables

​$wsCheckout.accountType

​$wsCheckout.guestMail

​$wsCheckout.selectedPayment / selectedShippingMethod

​$wsCheckout.selectedBillAddress / selectedShippingAddress

​$wsCheckout.draftBillAddressId / draftShippingAddressId

​$wsCheckout.draftBillAddress / draftShippingAddress

​$wsCheckout.useAlternativeShippingAddress

​$wsCheckout.selectedStoreId

​$wsCheckout.selectedPseudoCC

​$wsCheckout.orderId / orderCreatedAt

​$wsCheckout.customerData

​Structure of $wsCheckout.customerData

​Group object

​Field object

​$wsCheckout.freeFields

​Properties of a free field

​$wsCheckout.isValid

​$wsCheckout.isExpressCheckoutLocked

​$wsCheckout.isPPCExpressCheckout / isPPCApplePayExpressCheckout / isPPCGooglePayExpressCheckout

​$wsCheckout.paymentCaptchaRequired / paymentBlocked

​$wsCheckout.isOrderBlockedByIneffectiveVoucher

​$wsCheckout.ineffectiveVoucherErrors

​Properties of an error

​Meaning of the error codes

​$wsCheckout.verificationStatus / verificationStatusOptions

​$wsCheckout.voucherAppliesPerItem

​$wsCheckout.restUntilFreeDelivery / freeShippingMethod

​$wsCheckout.fieldStates

​$wsCheckout.problems

​Properties of an error

​Meaning of the error codes

​$wsCheckout.sum

​Properties of $wsCheckout.sum

​Methods

​$wsCheckout.isValidPayment()

​$wsCheckout.hasPaymentVault()

​$wsCheckout.isValidShippingMethod()

​$wsCheckout.isValidBillAddress() / isValidShippingAddress()

​$wsCheckout.isPending() / isFinished()

​$wsCheckout.getAmountInSmallestUnit()

​$wsCheckout.getShippingMethodDisabledErrors()

​$wsCheckout.getShippingCost()

​$wsCheckout.itemVoucherDiscount()

​Actions

​Examples

​Check whether the order can be placed and display errors

​Totals overview

​Check acceptance of terms and conditions

​Check the selected payment method

​Further links

Basic concept

Validation

Immediate errors and errors after an action

Selection IDs and draft addresses

Module overview

Templates

Variables

$wsCheckout.accountType

$wsCheckout.guestMail

$wsCheckout.selectedPayment / selectedShippingMethod

$wsCheckout.selectedBillAddress / selectedShippingAddress

$wsCheckout.draftBillAddressId / draftShippingAddressId

$wsCheckout.draftBillAddress / draftShippingAddress

$wsCheckout.useAlternativeShippingAddress

$wsCheckout.selectedStoreId

$wsCheckout.selectedPseudoCC

$wsCheckout.orderId / orderCreatedAt

$wsCheckout.customerData

Structure of `$wsCheckout.customerData`

Group object

Field object

$wsCheckout.freeFields

Properties of a free field

$wsCheckout.isValid

$wsCheckout.isExpressCheckoutLocked

$wsCheckout.isPPCExpressCheckout / isPPCApplePayExpressCheckout / isPPCGooglePayExpressCheckout

$wsCheckout.paymentCaptchaRequired / paymentBlocked

$wsCheckout.isOrderBlockedByIneffectiveVoucher

$wsCheckout.ineffectiveVoucherErrors

Properties of an error

Meaning of the error codes

$wsCheckout.verificationStatus / verificationStatusOptions

$wsCheckout.voucherAppliesPerItem

$wsCheckout.restUntilFreeDelivery / freeShippingMethod

$wsCheckout.fieldStates

$wsCheckout.problems

Properties of an error

Meaning of the error codes

$wsCheckout.sum

Properties of `$wsCheckout.sum`

Methods

$wsCheckout.isValidPayment()

$wsCheckout.hasPaymentVault()

$wsCheckout.isValidShippingMethod()

$wsCheckout.isValidBillAddress() / isValidShippingAddress()

$wsCheckout.isPending() / isFinished()

$wsCheckout.getAmountInSmallestUnit()

$wsCheckout.getShippingMethodDisabledErrors()

$wsCheckout.getShippingCost()

$wsCheckout.itemVoucherDiscount()

Actions

Examples

Check whether the order can be placed and display errors

Totals overview

Check acceptance of terms and conditions

Check the selected payment method

Further links