Skip to main content
This page describes the available services for validating user input as well as the rule-based checks for payment and shipping methods. In addition, there are hard-coded services that connect a payment method to a payment provider, check captchas or convert values between units. The services are not classic configuration nodes with their own structure, but are referenced in the respective form or rule definitions, for example in account, checkout or payment/shipping configurations. The reference consists of the service name in the format <Servicetyp>.<Implementierung> and, if required, an options object:
Check services are usually listed in a 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:
If the check does not take effect, the field is accepted without an error – the validation fails silently instead of rejecting the input. The same applies if listElements references an ID for which no address list exists (e.g. after a typo or after deleting the list).Therefore, if a field unexpectedly accepts arbitrary values, first check the spelling of the reference and the addressType of the list.
Further reading

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.
For the currently selected payment method, the reasons for a failed check are available under $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

There are no parameters for this service.

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

There are no parameters for this service.

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 in accounts.account.newCustomerRules at login. A new registration during checkout always results in the type newCustomer, regardless of the rules.
  • customer - any other signed-in customer. If no new-customer rules are configured, signed-in customers are always considered customer.
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 field invoiceToCompany:

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 parameter wsPaymentStatus=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.form in the captcha field protects a form. The check runs every time the InquirySend action is executed.
  • payment.paymentBlock in the captcha field 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.actionGuard in the captcha field protects any action.

Example configuration (inquiry.form.contact → captcha)

Both services first check cookie consent. If consent is missing for the consent service whose name is in the name 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:
The previous unit is the unit from the session. If none is stored there, the shop uses the unit stored in the customer account. If none is known there either, it calculates with the factor 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)

If the customer entered 2.5 in meters and switches to centimeters, the shop stores 2.5 × 100 ÷ 1 = 250.

Parameter overview