<Servicetyp>.<Implementierung> and, if required, an options object:
validations list, which can contain multiple entries. The other services are referenced via a single field of type singleService.
addressCheck.* - Address validations
addressCheck.* contains checks for address fields (e.g. name, street, ZIP). The checks are stored in the respective field definitions under validations.
The frontend displays the fields as configured and checks during input whether the entries are valid. This detects incorrect or invalid values early.
addressCheck.minLength - Minimum length
Checks the minimum length of the input in address fields.
Example configuration for (accounts.addressField.firstName)
Parameter overview
addressCheck.maxLength - Maximum length
Checks the maximum length of the input in address fields.
Example configuration for (accounts.addressField.firstName)
Parameter overview
addressCheck.numeric - Digits only
Checks whether the input in address fields consists only of digits.
Example configuration for (accounts.addressField.phone)
Parameter overview
addressCheck.country - Country code (ISO)
Checks whether the input or selection in country lists of the address data fields is a country code configured in the shop (ISO code: 2-letter, 3-letter or ISO number).
The official ISO-3166-1 codes (alpha-2, alpha-3 and numeric) can be found on the website of the International Organization for Standardization (ISO): https://www.iso.org/iso-3166-country-codes.html
Example configuration for (accounts.addressField.country)
Parameter overview
addressCheck.zip - ZIP / postal code
Checks whether the input is a valid ZIP/postal code for the specified country. The ZIP rules come from the configuration. The associated country must be provided in the country field.
Example configuration for (accounts.addressField.zip)
Parameter overview
addressCheck.salutation - Salutation (code)
Checks whether the input is a valid salutation (code according to configuration).
Example configuration for (accounts.addressField.salutationCode)
Parameter overview
addressCheck.regex - Regular expression
Checks whether the input matches a regular expression.
Example configuration for (accounts.addressField.additionalInfo)
Parameter overview
addressCheck.phone - Phone number
Checks whether the input is a valid phone number. A valid number consists of digits (without length restriction) and optionally an international dialling code.
The + in the dialling code is replaced by 00 after successful validation.
Example configuration for (accounts.addressField.phone)
Parameter overview
addressCheck.alpha - Letters only (A–Z)
Checks whether the input consists only of Latin letters (case-insensitive).
Example configuration for (accounts.addressField.additionalInfo)
Parameter overview
addressCheck.alphanum - Letters/digits (A–Z/0–9)
Checks whether the input consists only of Latin letters or digits (case-insensitive).
Example configuration for (accounts.addressField.additionalInfo)
Parameter overview
addressCheck.legalSigns - Allowed characters
Checks whether all characters in the input are contained in the allowed character set (case-sensitive).
Example configuration for (accounts.addressField.additionalInfo)
Parameter overview
addressCheck.illegalSigns - Forbidden characters
Opposite of legalSigns: the input must not contain any of the specified characters.
Example configuration for (accounts.addressField.phone)
Parameter overview
addressCheck.date - Date
Checks whether the input is a valid date and formats the input if needed.
Example configuration for (accounts.addressField.additionalInfo)
Parameter overview
addressCheck.allowedSelection - Selection (list element)
Validates whether the input matches a predefined selection value. The permitted values come from an address list under general.addressListElements, which is referenced via listElements.
Typical use: check whether an address is, for example, a “packstation” or “private address”.
Example configuration for (accounts.addressField.addressType)
Parameter overview
Interplay with the list’s
addressType
Whether the check takes effect at all depends on the addressType parameter of the referenced list:
Further reading
general.addressListElements– definition of the lists and their permitted values.- $wsConfig.listElements – output of the same list as a selection field in the form.
dataChecker.* - General field validations
dataChecker.* contains checks for general form fields that are not specific to an address. The checks are included in the respective field definition under validations.
The frontend takes the specifications from the field definition and checks during input whether the entry is correct (e.g. length, format or forbidden characters).
If a check fails, the shop outputs an error text that matches the respective check, for example “The input is too short.” for dataChecker.minLength. The texts for all dataChecker.* services are stored together in the general.dataCheckerValidationErrors node. For the additional fields of payment methods and for the online order form, subCode in the error object additionally names the failed service, for example dataChecker.minLength.
dataChecker.minLength - Minimum length
Checks the minimum length of the inputs in form input fields.
Example configuration for (inquiry.form.catalogue.fields.firstName)
Parameter overview
dataChecker.maxLength - Maximum length
Checks the maximum length of the inputs in form input fields.
Example configuration for (inquiry.form.catalogue.fields.firstName)
Parameter overview
dataChecker.numericChecker - Digits only
Checks whether the input in form input fields consists only of digits.
Example configuration for (inquiry.form.catalogue.fields.phone)
Parameter overview
dataChecker.countryChecker - Country code (ISO)
Checks whether the input or selection in country lists of the form fields is a country code configured in the shop (ISO code: 2-letter, 3-letter or ISO number).
The official ISO-3166-1 codes (alpha-2, alpha-3 and numeric) can be found on the website of the International Organization for Standardization (ISO): https://www.iso.org/iso-3166-country-codes.html
Example configuration for (inquiry.form.catalogue.fields.country)
Parameter overview
dataChecker.zipCodeChecker - ZIP / postal code
Checks whether the input is a valid ZIP/postal code for the specified country. The ZIP rules come from the configuration. The associated country must be provided in the country field.
Example configuration for (inquiry.form.catalogue.fields.zip)
Parameter overview
dataChecker.salutation - Salutation (code)
Checks whether the input is a valid salutation (code according to configuration).
Example configuration for (inquiry.form.catalogue.fields.salutation)
Parameter overview
dataChecker.regex - Regular expression
Checks whether the input matches a regular expression.
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.email - Email address
Checks whether the input is a valid email address.
Example configuration for (inquiry.form.catalogue.fields.mail)
Parameter overview
dataChecker.alphaClass - Letters (min/different)
Ensures that the input contains at least minChars Latin letters (case-insensitive); optionally a minimum number of different letters.
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.lowerAlphaClass - Lowercase letters
Like alphaClass, but only lowercase letters.
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.upperAlphaClass - Uppercase letters
Like alphaClass, but only uppercase letters.
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.digitClass - Digits
Like alphaClass, but for digits.
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.specialClass - Special characters
Like alphaClass, but for special characters.
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.sequenceOfIdenticalCharacters - Repeated characters (sequence)
Checks whether the same character occurs too often in a row.
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.consecutiveNumbers - Consecutive numbers
Checks for ascending or descending number sequences (e.g. 12345 or 54321).
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.consecutiveLetters - Consecutive letters
Checks for ascending or descending letter sequences (e.g. abcd or dcba).
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
dataChecker.palindrome - Palindrome
Checks whether the input is a palindrome (identical forwards/backwards, e.g. “Otto”).
Example configuration for (inquiry.form.catalogue.fields.additionalInfo)
Parameter overview
paymentValidation.* - Payment method validation
paymentValidation.* contains rules that determine whether a payment method is allowed in the checkout. The check can depend, for example, on the country of the billing or shipping address, the customer type, the basket or the order value.
These rules can be entered in the configuration of the respective payment method under validations. The frontend then only shows the payment methods that match, or prevents the selection when the conditions are not met. Here is the link to the corresponding configuration node payment: payment - Payment methods
Evaluation in the frontend
In the template, the configured rules are evaluated via the method $wsCheckout.isValidPayment(paymentId): it runs all services stored under validations and returns false as soon as at least one rule fails. Unavailable payment methods are therefore disabled or hidden in the selection.
$wsCheckout.problems.payment. The subCode field names the failed service.
paymentValidation.billCountry - Validation of the country (billing address) for payment methods
Checks whether the country of the billing address is allowed for a payment method according to an “allow/deny” list. Via the options you can define which countries the rule applies to and whether this list allows or forbids countries.
Example configuration
Parameter overview
paymentValidation.billPhone - Validation of the phone number
Checks whether a phone number is provided for the billing address (the field must not be empty).
Example configuration
paymentValidation.billDateOfBirth - Validation of the date of birth
Checks whether a date of birth is provided for the billing address (the field must not be empty).
Example configuration
paymentValidation.shippingCountry - Validation of the country (shipping address)
Checks whether the country of the shipping address is allowed according to an “allow/deny” list. Via the options you can define which countries the rule applies to and whether this list allows or forbids countries.
Example configuration
Parameter overview
paymentValidation.shippingMethod - Validation of the shipping method for payment methods
Checks whether the selected payment method may only be used with certain shipping methods.
Example configuration
Parameter overview
paymentValidation.accountType - Validation of the customer type for payment methods
Checks whether the selected payment method may only be used for certain customer types (guest, new customer or existing customer).
Example configuration
Parameter overview
How the customer type is determined
guest- the customer orders as a guest (without a user account).newCustomer- a signed-in customer who fulfils the new-customer rules configured inaccounts.account.newCustomerRulesat login. A new registration during checkout always results in the typenewCustomer, regardless of the rules.customer- any other signed-in customer. If no new-customer rules are configured, signed-in customers are always consideredcustomer.
The customer type checked here is not identical to the template variable
$wsCheckout.accountType (guest / new / registered): the latter reports the sign-in method chosen in the checkout, while the validation distinguishes between new and existing customers (newCustomer / customer). In the order data, customer and newCustomer are both reported as registered.paymentValidation.denyDifferingShippingAddress - Validation of differing shipping addresses for payment methods
Checks whether the billing and shipping addresses are identical.The payment method is only allowed when no differing shipping address is used.
Example configuration
Parameter overview
paymentValidation.voucherDeny - Validation of voucher products for payment methods
Checks whether voucher products are in the basket. When voucher products are in the basket, this payment method is not allowed.
Example configuration
Parameter overview
paymentValidation.total - Validation of minimum / maximum order value for payment methods
Checks whether the payment method may only be used when a certain minimum or maximum order value is reached or not exceeded.
Example configuration
Parameter overview
If both a minimum and a maximum order value are to be checked at the same time, this check must be configured twice with different options.
paymentValidation.inventoryState - Validation of the inventory state for payment methods
Checks whether products with a specific stock level are in the basket. If a product in the basket has a status configured in deny, the payment method is not allowed.
Example configuration
Parameter overview
paymentValidation.productDependency - Validation of product dependencies for payment methods
Checks the products in the basket against the configuration checkout.productDependency.A payment method is only offered when all referenced product dependencies are fulfilled. This way you couple a payment method to basket properties without duplicating the check logic. The actual conditions (product fields, free fields, value comparisons) are maintained centrally in checkout.productDependency.
Example configuration
The “Pay by invoice” option should be blocked as soon as a personalised product (e.g. with an engraving) is in the basket. Because personalised items cannot be returned, they carry a higher payment-default risk. You define the condition “no engraving in the basket” in checkout.productDependency and reference it here afterwards.Parameter overview
paymentValidation.userAgent - Validation of the user agent for payment methods
Checks whether a payment method is displayed based on the customer’s device or browser. Devices and browsers automatically transmit a technical identifier when a page is called up — the so-called user agent. Based on this identifier, it can be detected, for example, whether someone is using an iPhone, an iPad or a Mac.
The terms entered in userAgents are checked against this identifier; a single match is enough. This allows a payment method to be enabled or blocked specifically for certain devices or browsers — for example, when Apple Pay should only be displayed to customers using an Apple device or a compatible browser.
Example configuration
Parameter overview
paymentFieldDisplayCheck.* - Display conditions for additional fields
paymentFieldDisplayCheck.* contains conditions that control when an additional field of a payment method is displayed in the checkout. For example, a field appears only for certain billing countries or only if another additional field has a specific value.
The conditions are entered in the field definition under displayConditions. If multiple conditions are stored, all of them must be met. Unlike the checks under validations, the conditions do not produce an error message. If a condition is not met, the shop hides the field, does not check it and does not require it, even as a required field.
If a condition cannot be evaluated, it is considered not met and the field remains hidden. This applies, for example, to an address that cannot be loaded or to an incomplete configuration. The cause is then recorded in the LogManager.
paymentFieldDisplayCheck.billCountry / shippingCountry - Country of the billing or shipping address
Checks the country of the billing address (billCountry) or shipping address (shippingCountry) selected in the checkout against a country list.
Example configuration
Parameter overview
The condition is not met if the address cannot be loaded or its country is not configured as an active country node.
Without a differing shipping address,
shippingCountry checks the country of the billing address.paymentFieldDisplayCheck.billAddressField / shippingAddressField - Field of the billing or shipping address
Checks a single field of the billing address (billAddressField) or shipping address (shippingAddressField) selected in the checkout.
Example configuration
The field is only displayed if the billing address does not contain a company:Parameter overview
The condition is not met if the address cannot be loaded,
field or type is missing, the field does not exist in the address or type has an unknown value.
paymentFieldDisplayCheck.paymentField - Value of another additional field
Checks the current value of another additional field from the current checkout. This lets you build dependent fields that only appear after a specific input.
Example configuration
The field is only displayed if the checkbox is checked in the additional fieldinvoiceToCompany:
Parameter overview
The condition is not met if
field or type is missing or type has an unknown value.
The shop only stores the value of an additional field with the
CheckoutSetPaymentFields action. A dependent field therefore only appears after the form has been submitted, for example automatically on every change.shippingMethodValidation.* - Shipping method validation
shippingMethodValidation.* contains rules that determine whether a shipping method is allowed in the checkout. The check can depend, for example, on the shipping country, the goods value, product types or the selected payment method.
These rules can be entered in the configuration of the respective shipping method under validations. The frontend then only offers the shipping methods that match the current conditions.
Evaluation in the frontend
In the template, the configured rules are evaluated via the method $wsCheckout.isValidShippingMethod(shippingMethodId) (same pattern as for payment methods). The reasons for a disabled shipping method can additionally be output via $wsCheckout.getShippingMethodDisabledErrors(shippingMethodId).
shippingMethodValidation.shippingCountry - Validation of the country (shipping address)
Checks whether the country of the shipping address is allowed according to an “allow/deny” list. Via the options you can define which countries the rule applies to and whether this list allows or forbids countries.
Example configuration
Parameter overview
shippingMethodValidation.paymentMethod - Validation of the payment method for shipping methods
Checks whether a shipping method may only be used with certain payment methods.
Example configuration
Parameter overview
shippingMethodValidation.valueOfGoods - Validation of the minimum/maximum order value for shipping methods
Checks whether the shipping method may only be used when a certain minimum or maximum order value is reached or not exceeded.
Example configuration
Parameter overview
shippingMethodValidation.productType - Validation of the product type for shipping methods
Checks whether all products in the basket have a matching product type.
Example configuration
Parameter overview
shippingMethodValidation.productDependency - Validation of product dependencies for shipping methods
Checks the products in the basket against the configuration checkout.productDependency.
Example configuration
Parameter overview
shippingMethodValidation.expressCheckout - Validation of the express checkout for shipping methods
Checks whether a shipping method is allowed depending on the payment method used in the express checkout. The check applies to PayPal Express as well as Apple Pay and Google Pay Express (PayPal Commerce Platform).
Example configuration
The shipping method should not be selectable if the customer runs the ordering process as a PayPal Express Checkout:Parameter overview
If the check fails, the validation returns the error
expressCheckoutDenied or expressCheckoutNotAllowed. In the frontend, it can be output via $wsCheckout.getShippingMethodDisabledErrors().
payment.* - Online clearing services
An online clearing service processes the payment of a payment method in real time via a payment provider. The assignment is made in the payment method under payment.payment in the onlineClearing field. Payment methods without onlineClearing are considered offline payment methods, for example prepayment or invoice without a provider.
Unlike the validation and check services, an online clearing service is not referenced in a validations list but via a field of type singleService. Each payment method references exactly one service. The provider-specific settings are stored in the payment.computopHosted, payment.stripe and payment.payPalCheckout nodes. The service options only control which shop pages the customer is directed to during payment.
Pending payments and pending page
All three services support a pending page. The shop displays it while a payment has not yet been completed at the provider. During this time, the session is locked. The customer can then only open the pending page, the order confirmation, the order flow and the home page. If they open any other page, the shop redirects them back to the pending page. The shop appends the parameterwsPaymentStatus=refresh to the URL of the pending page. If the payment has been completed in the meantime, the shop redirects directly to the order confirmation when the pending page is opened.
If no pending page is stored in the service options, the shop falls back to the pendingTemplate field in the general.subshopView node. The exact order per provider is described in the following sections.
payment.computop-hosted - Computop Hosted Payment Page
Redirects the customer to Computop’s hosted payment page. To do this, the shop first renders its own page with a form that passes the payment data to Computop via POST. This page is defined via the view option.
The ID of the payment method under payment.payment must match the id of an entry under payment.computopHosted and correspond to a payment method supported by Computop. Otherwise, the shop aborts the payment with the log message payment method invalid, not defined in computopHosted config.
Example configuration (payment.payment.creditcard → onlineClearing)
Parameter overview
payment.stripe - Stripe
Connects Stripe as a payment provider. The payment runs via the Stripe widget in the order flow. If the customer selects a payment option with a redirect in the widget, they return to the shop via the page from the view option.
The Stripe account settings are stored in the payment.stripe node. The integration in the template is described in Stripe in the frontend.
Example configuration (payment.payment.stripe → onlineClearing)
Parameter overview
payment.paypal-checkout - PayPal Checkout
Connects PayPal Checkout (PayPal Commerce Platform) as a payment provider. The return pages for confirmation, cancellation and errors are defined by the payment.payPalCheckout node. The service’s view option defines the page for payments that are still pending after submission, for example for purchase on invoice via PayPal.
Example configuration (payment.payment.paypalCheckout → onlineClearing)
Parameter overview
captchaCheck.* - Captcha check
A captcha service checks whether a request comes from a human. To do this, the frontend integrates the provider’s captcha and sends its token to the shop with the action. The service forwards the token to the provider for verification.
The provider’s credentials are stored in the security node. The reference to the service determines which provider performs the check at a given point. Three places can use a captcha service:
inquiry.formin thecaptchafield protects a form. The check runs every time theInquirySendaction is executed.payment.paymentBlockin thecaptchafield secures order completion against repeated payment attempts. The check only runs once the shop requires a captcha after several failed attempts. Whether this is the case is output by$wsCheckout.paymentCaptchaRequired.security.actionGuardin thecaptchafield protects any action.
Example configuration (inquiry.form.contact → captcha)
Consent and request parameters
Both services first check cookie consent. If consent is missing for the consent service whose name is in thename field of the provider node, the check fails without a request to the provider. The name field must therefore match the name of the service in consent management.
The shop expects the token in a fixed request parameter of the action. The name cannot be configured.
If the check fails for
InquirySend or at order completion, the action returns the error code captchaFailed. You maintain the corresponding text in the action’s error text node, for example under actions.inquirySend.
captchaCheck.recaptchav3 - Google reCAPTCHA v3
Checks a Google reCAPTCHA v3 token. Google returns a score between 0.0 and 1.0 for each token. If it is below minimumScore from security.recaptchav3, the check is considered failed.
Example configuration
Parameter overview
captchaCheck.friendlyCaptchaV1 - Friendly Captcha v1
Checks a Friendly Captcha v1 solution. The shop sends the solution together with apiKey and siteKey from security.friendlyCaptchaV1 to the provider’s verifyUrl.
Example configuration
Parameter overview
unitConverter.* - Unit conversion
A customer data field of type number can have a dynamic unit. The customer then selects the unit from a list, for example meters or centimeters. If they change the unit, a conversion service converts the entered value to the new unit.
The service is entered in the customer data field under customer.customerDataField in the type.number.unit.dynamic.converter field. Without an entry, the shop stores the value unchanged with the new unit.
unitConverter.orderOfMagnitude - Conversion using factors
Converts using the factors stored on the units under unitOptions. The service itself has no options.
The conversion follows this formula:
1. If the factor of the previous unit is 0, the conversion results in 0.
The factor indicates how many units correspond to a reference quantity. You should therefore give the base unit from baseUnitName the factor 1. This way, the conversion is also correct if no previous unit is known.
Example configuration (customer.customerDataField.raumhoehe → type)
2.5 in meters and switches to centimeters, the shop stores 2.5 × 100 ÷ 1 = 250.
