payment - Payment methods - WEBSALE Dokumentation

The payment node bundles the complete payment configuration of the shop, including individual payment methods (display, rules) and payment providers such as PayPal, Stripe, or Computop.

`payment*` - Basic structure

Below is the basic structure of the payment node

{
  "payment": {
    "payment": {},
    "paymentField": {},
    "computopHosted": {},
    "payPalCheckout": {},
    "payPalCheckoutErrors": {},
    "payPalPlus": {},
    "stripe": {},
    "stripeErrors": {},
    "transactionSettings": {}
  }
}

Parameter description

Parameter	Description
`payment`	Controls which payment methods are offered in the shop.
`paymentField`	Creates additional fields that are requested in the checkout together with a payment method, for example the date of birth for purchase on invoice.
`computopHosted`	Configures the connection to Computop.
`payPalCheckout`	Configures the connection to PayPal Checkout.
`payPalCheckoutErrors`	Defines the error texts that the buyer sees after a declined PayPal payment.
`payPalPlus`	Configures the connection to PayPal Plus.
`stripe`	Configures the connection to Stripe.
`stripeErrors`	Defines the error texts that the buyer sees after a declined Stripe payment.
`transactionSettings`	Centrally defines which functions are supported by the payment providers, for example `refund`, `cancel`, `refresh`, and `capture`.

`payment.computopHosted` - Computop Hosted Payments

With payment.computopHosted, Computop can be integrated as a hosted payment page. The node controls, for example, operating mode (Live / Test), encryption, and the language / template of the payment page. Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden: https://<shop-domain>/admin/config/payment.computopHosted (Deeplink-Übersicht)

Example configuration (`payment.computopHosted.creditcard`)

{
  "callbackUrl": "",
  "capturingMode": "auto",
  "chDesc": "",
  "encryption": "blowfish",
  "hmacKey": "",
  "hostedCheckBoxDefaultChecked": false,
  "hostedTemplateName": "Websale",
  "id": "creditcard",
  "languageCode": "",
  "linkValidForSeconds": 500,
  "mode": "test",
  "passCredentialOnFile": true,
  "pwLarge": "",
  "sendIPAddr": true,
  "sendIPZone": true,
  "sendZone": true,
  "totalSumAddition": 0,
  "uid": "Websale"
}

Parameter description

Parameter	Type	Description
`callbackUrl`	string	Name of the shop template (view) that Computop redirects the customer to after payment. The return address is built from the URL of this template. The outcome of the payment is appended as URL parameter `wsPaymentStatus` (`refresh` or `cancel` on cancellation).
`capturingMode`	enum	Allowed values: `auto` = the payment is checked and directly captured in one step. `manual` = at checkout the amount is only reserved, but not yet charged.
`chDesc`	string	Text displayed to the payer (e.g. on the card statement).
`encryption`	enum	Allowed values: `aes` = modern encryption option. `blowfish` = older encryption option that is still supported.
`hmacKey`	string	Secret key for data checks against Computop.
`hostedCheckBoxDefaultChecked`	bool	Sets a consent checkbox provided by Computop to active or not active (`true` / `false`).
`hostedTemplateName`	string	Name of the template of the hosted Computop payment page.
`id`	string	Unique identifier of the payment method, for example `creditcard`. Must match the `id` of the payment method under `payment.payment` that references the `payment.computop-hosted` service via `onlineClearing`, and must correspond to a payment method supported by Computop. More under Validation and check services.
`languageCode`	string	Language of the hosted page (e.g. `de`, `en`). Empty = Computop default.
`linkValidForSeconds`	int	Validity period of the payment link in seconds.
`mode`	enum	Operating mode of the Computop integration. Allowed values: - `test` = for sandbox tests - `live` = use in production.
`passCredentialOnFile`	bool	Flags “card data stored” for follow-up transactions, if supported.
`pwLarge`	string	Additional password according to the Computop specification. The password is used for the encrypted transmission.
`sendIPAddr`	bool	Sends the customer’s IP address to Computop.
`sendIPZone`	bool	Sends the zone derived from the IP (e.g. country / region) to Computop.
`sendZone`	bool	Sends the shop zone (e.g. delivery zone) to Computop.
`totalSumAddition`	float	Fixed surcharge/deduction in currency units on the total sum of the payment method (e.g. `0.30`). `0` = no surcharge/deduction. Only possible when `capturingMode` has the value `manual`.
`uid`	string	Merchant / account ID at Computop.

`payment.payment` - Create payment methods

The payment.payment node bundles all payment methods of the shop. Here you can, for example, define whether a payment method is active, how it should be named and look in the checkout, which provider handles it, and which rules apply. Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden: https://<shop-domain>/admin/config/payment.payment (Deeplink-Übersicht)

Payment methods can be bound to a currency or region (e.g. Bancontact: only EUR, primarily Belgium). Which currencies and countries a payment method supports is determined by the payment service provider. An activated payment method is therefore offered regardless of the shop currency and may cause an error at the payment service provider. Before activation, check the provider documentation to see whether the payment method fits the currency and target country of your shop, and deactivate any methods that do not fit.

If the checkout spans multiple pages and the Stripe widget is to be loaded before the order overview, create a separate payment method with Stripe as the clearing service for Google Pay and for Apple Pay. The template can then refer to the selected wallet from the payment methods page onwards. The integration in the template is described in Stripe in the frontend.

Example configuration (`payment.payment.paypalCheckout`)

{
  "active": true,
  "additionalFields": [],
  "availableByDefault": true,
  "basicCost": [
    { "subtotal": 0, "cost": 2.5 },
    { "subtotal": 50, "cost": 0 }
  ],
  "description": "<text snippet>",
  "longDescription": "<text snippet>",
  "discount": 0,
  "displayedPaymentTypes": null,
  "freeFields": null,
  "id": "paypalCheckout",
  "image": "",
  "labels": ["<text snippet>"],
  "name": "<text snippet>",
  "onlineClearing": {
    "options": {
      "view": "paypal_checkout_pending.htm"
    },
    "service": "payment.paypal-checkout"
  },
  "orderText": "<text snippet>",
  "provider": "",
  "type": "",
  "validations": [
    { "service": "paymentValidation.voucherDeny" }
  ]
}

Parameter description

Parameter	Type	Description
`active`	bool	Payment method in checkout on / off.
`availableByDefault`	bool	Controls whether the payment method is available by default for all customers (default: `true`). With `false`, the payment method is not available to guests and normal customer accounts. It can then be enabled for individual customer accounts specifically by adding the payment method to the account’s `enabledPaymentMethods` list via the admin API (see API reference customer data). Conversely, a payment method available by default can be blocked for individual accounts via the `blockedPaymentMethods` list.
`id`	string	Unique identifier of the payment method, e.g. `paypalCheckout`
`name`	text snippet (string)	Display name in the checkout, e.g. “PayPal”. Dieser Text wird über einen Textbaustein realisiert. Alles zu Textbausteinen in Konfigurationen finden Sie hier.
`orderText` (coming soon)	text snippet (string)	Technical transfer value for connected third-party systems that is exported with the order. Dieser Text wird über einen Textbaustein realisiert. Alles zu Textbausteinen in Konfigurationen finden Sie hier.
`labels` (coming soon)	list / text snippet (string)	Optional short label for the payment method that can be shown as a hint in the checkout. Dieser Text wird über einen Textbaustein realisiert. Alles zu Textbausteinen in Konfigurationen finden Sie hier.
`type` (coming soon)	string	Describes the type of payment processing and helps with the display in the checkout. Common values are, for example: `online` - payment runs via a provider. `offline` - payment is processed manually.
`onlineClearing`	singleService	Links the payment method to a specific online payment engine and thereby enables the real-time payment flow. Available services: `payment.computop-hosted`, `payment.stripe`, `payment.paypal-checkout`. `options` defines which pages the customer is directed to during payment. For PayPal purchase on invoice, this also includes `clearingFields`; see Example: PayPal purchase on invoice. More at: Validation and check services target: `payment`
`provider` (coming soon)	string	Technical provider key (e.g. `stripe`)
`image` (coming soon)	string	Icon/logo URL for the payment method.
`basicCost`	list (object)	Costs of the payment method, tiered by the subtotal of the basket. Per entry: - `subtotal` (float) - subtotal from which the entry applies - `cost` (float) - cost of the payment method in currency units In the example above, the payment method costs 2.50 and is free from a subtotal of 50. In the checkout, the costs flow into `$wsCheckout.sum.paymentCost`.
`displayedPaymentTypes`	list (object)	With this parameter, multiple entries with their own name, icon, image, or description can be stored for a payment method. This is particularly relevant when, for example, payment providers such as Stripe are configured directly as payment methods, but the included payment options should be shown separately outside of the order flow - e.g. in the footer or on a payment methods information page. The display of the included payment options in the order flow is usually handled by the respective provider. The following properties can be set per entry: - `name` - display name of the payment option - `image` - path or URL to an image / icon of the payment option - `description` - description text of the payment option The output in the template is done via the variable of the $wsConfig module, through which the configured entries can be output in the frontend at the desired location.
`validations`	multiService	Rules and checks for the availability of a payment method (e.g. `paymentValidation.voucherDeny` - blocks the payment method for voucher baskets, `paymentValidation.userAgent` - restricts the payment method to certain devices or browsers). More at: Validation and check services target: `paymentValidation`
`discount` (coming soon)	float	Discount / deduction in currency units. (e.g. `2.00` - customer pays 2€ less with this payment method).
`description`	text snippet (string)	Longer description / notes about the payment method. Dieser Text wird über einen Textbaustein realisiert. Alles zu Textbausteinen in Konfigurationen finden Sie hier.
`longDescription`	text snippet (string)	Even more detailed variant of the description text than `description`, for example for a payment methods information page or detailed notes. Dieser Text wird über einen Textbaustein realisiert. Alles zu Textbausteinen in Konfigurationen finden Sie hier.
`freeFields`	list (string)	Free fields, for example for additional information for purchase on account such as date of birth or company information. Currently only used for Computop. For new additional fields, use `additionalFields`.
`additionalFields`	multiAssoc, optional	Additional fields that are requested in the checkout together with this payment method. The fields are created in `payment.paymentField` and assigned here by node ID. target: `payment.paymentField`

`payment.paymentField` - Additional fields for payment methods

Some payment methods require information that is not part of the address. PayPal purchase on invoice, for example, requires the buyer’s date of birth and phone number. With the payment.paymentField node, you create such additional fields. The shop requests them in the checkout together with the payment method and writes the inputs to the order data. From there, they can be exported to external systems like all other order data. You create an additional field in three steps:

Create the field in payment.paymentField.
Assign the field to the payment method under additionalFields; see payment.payment.
Output the field in the template and save it with the CheckoutSetPaymentFields action. The fields of a payment method are available in the template under $wsConfig.payments in the fields entry.

Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden: https://<shop-domain>/admin/config/payment.paymentField (Deeplink-Übersicht)

Example configuration (`payment.paymentField.birthdatePayPal`)

The example creates a required field for the date of birth. The value is remembered in the customer account and must match the format JJJJ-MM-TT (YYYY-MM-DD).

{
  "displayConditions": null,
  "infoText": null,
  "label": "config.payment.paymentField.birthdate.label",
  "name": "bday",
  "rememberInput": true,
  "required": true,
  "type": {
    "checkbox": null,
    "date": {},
    "select": null,
    "text": null
  },
  "validations": [
    {
      "options": {
        "expression": "(19|20)[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])"
      },
      "service": "dataChecker.regex"
    }
  ]
}

dataChecker.regex checks whether the entire value matches the expression. A date field always returns month and day with two digits, for example 1990-05-01. The expression must therefore allow leading zeros.

Parameter description

Parameter	Type	Description
`name`	string	Technical name of the field. The value is available under this name in the template, in the order data and in references from other configurations, for example in `clearingFields` of a payment method. This name is decisive, not the ID of the configuration node.
`label`	text snippet (string)	Label of the field in the checkout. Dieser Text wird über einen Textbaustein realisiert. Alles zu Textbausteinen in Konfigurationen finden Sie hier.
`infoText`	text snippet (string), optional	Additional note on the field, for example why the information is needed. Dieser Text wird über einen Textbaustein realisiert. Alles zu Textbausteinen in Konfigurationen finden Sie hier.
`required`	bool	Marks the field as required. An empty required field prevents order completion with the error code `requiredPaymentFieldEmpty`; an unchecked required checkbox with `requiredPaymentCheckboxUnchecked`.
`type`	oneOf	Field type. Exactly one option is set; the others are `null`. - `text` - text input - `checkbox` - checkbox; the stored value is `true` or `false` - `select` - selection list. The entries are under `select.options`, each with `value` (submitted value) and `label` (displayed text, text snippet). A value that is not in the list is not applied. - `date` - date input
`rememberInput`	bool	Remembers the entered value in the customer account after the order; see Remembering inputs.
`validations`	multiService, optional	Checks for the entered value. All services from `dataChecker.*` can be used. If a check fails, the error code is `fieldCheckFailed`. The error text comes from `general.dataCheckerValidationErrors`. target: `dataChecker`
`displayConditions`	multiService, optional	Conditions under which the field is displayed in the checkout. All conditions must be met. Without a condition, the field is always displayed. The services from `paymentFieldDisplayCheck.*` can be used. target: `paymentFieldDisplayCheck`

A field whose display conditions are not met is treated as non-existent. It does not appear in the template, is not checked and, even as a required field, does not block order completion.

Multiple fields with the same name

Because the shop addresses additional fields via name, multiple configuration nodes can have the same name. This lets you request the same information differently depending on the situation, for example with country-dependent selection lists or checks. The variants are then distinguished via displayConditions.

The display conditions of fields with the same name must be mutually exclusive. If two fields with the same name are visible at the same time, both write to the same value.

Remembering inputs

With rememberInput: true, the shop stores the entered value in the customer account after the order. This only applies to logged-in customers. For guest orders, the value remains in the current session and is not stored. The remembered value is not inserted automatically at the next checkout. The template decides whether to prefill the field with it. The value is available there as rememberedValue on the field; see $wsConfig.payments.

Additional fields in the order data

With the order, the shop writes the additional fields of the selected payment method to the order.paymentFields block. The key is the technical name of the field, the value is the customer’s input:

"paymentFields": {
  "bday": "1990-05-01",
  "phone": "+491701234567"
}

All fields assigned to the payment method are included. A field that was not displayed because of its display condition is included with an empty value or with an earlier input from the same session.

Example: PayPal purchase on invoice

For purchase on invoice, PayPal requires the buyer’s date of birth and phone number. You define which additional fields provide this information in the payment method under onlineClearing.options.clearingFields:

"onlineClearing": {
  "options": {
    "clearingFields": {
      "birthdate": "bday",
      "phone": "phone"
    },
    "type": "invoice"
  },
  "service": "payment.paypal-checkout"
}

The shop passes the value of the additional field bday to PayPal as the date of birth and the value of phone as the phone number. In each case, you enter the technical name from name, not the ID of the configuration node. Both fields must also be assigned to the payment method under additionalFields; otherwise the checkout does not request them.

Parameter	Type	Description
`clearingFields.birthdate`	string	Technical name of the additional field whose value is sent to PayPal as the date of birth. PayPal expects the format `JJJJ-MM-TT` (YYYY-MM-DD).
`clearingFields.phone`	string	Technical name of the additional field whose value is sent to PayPal as the phone number.

For the phone number, the shop reads the country code from the beginning of the input. If the number starts with + or 00, the following two digits are treated as the country code. If neither is present, the shop assumes the country code 49 for Germany. This rule splits country codes with one or three digits incorrectly, for example +1 or +352. The shop does not pass on numbers with four characters or fewer. A check via validations in the additional field catches incorrect formats before PayPal rejects the payment.

Without clearingFields, the shop takes the date of birth and phone number from the billing address. This behavior is only intended for existing shops and is considered deprecated. New setups use additional fields.

`payment.payPalCheckout` - PayPal Checkout configuration

The payment.payPalCheckout node configures the PayPal Checkout in the shop. This includes, for example, activation, setting the mode (Live / test mode), and the language. Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden: https://<shop-domain>/admin/config/payment.payPalCheckout (Deeplink-Übersicht)

Example configuration

{
  "active": true,
  "approvalTemplate": "",
  "brandName": "Websale AG",
  "cancelTemplate": "",
  "customerServiceInstructions": null,
  "denyPendingPayments": true,
  "dummyProductAddition": "dummy product",
  "errorTemplate": "",
  "expressCheckoutAllow": true,
  "expressCheckoutApplePayAllow": false,
  "expressCheckoutGooglePayAllow": false,
  "languageCode": "de-DE",
  "logoUrl": "",
  "mode": "sandbox",
  "payerId": ""
}

Parameter description

Parameter	Type	Description
`active` (coming soon)	bool	Enables / disables PayPal Checkout.
`payerId`	string	PayPal Merchant ID of the merchant account.
`dummyProductAddition`	string	Optional additional text for item names in case PayPal requires a minimum entry (e.g. placeholder for empty names).
`denyPendingPayments`	bool	`true` - orders with the PayPal status “pending” are rejected or not continued. The buyer then sees the text `pendingPaymentDenied` from `payment.payPalCheckoutErrors`. `false` - “pending” is allowed.
`brandName`	string	Merchant name that is displayed.
`languageCode`	string	Display language for PayPal (e.g. `de-DE`, `en-US`).
`logoUrl`	string	URL to a logo for the display in the PayPal checkout.
`customerServiceInstructions`	list (string)	Optional customer notes that can be displayed in the PayPal context.
`mode`	enum	Operating mode of the PayPal checkout. `sandbox` - test mode `live` - production mode Default: `sandbox`
`pendingTemplate`	string	Name of the shop template (view) that the customer sees while a PayPal payment is still pending, for example for purchase on invoice. Applies if no `view` option is set in the payment method’s `onlineClearing`. If this value is also empty, the shop uses `pendingTemplate` from `general.subshopView`.
`approvalTemplate`	string	Name of the shop template (view) that the customer is redirected to after successful confirmation of the PayPal payment. The return address is built from the URL of this template, with the URL parameter `wsPaymentStatus=refresh`. It is available in the frontend as `approvalUrl` or `expressApprovalUrl` in the return value of `$wsPayPalCheckout.loadData()`. Default: `checkout.htm`
`errorTemplate`	string	Name of the shop template (view) that the customer is redirected to in the event of an error in the PayPal SDK (URL parameter `wsPaymentStatus=error`). There, the customer sees the reason under `$wsCheckout.problems.clearing`. Available in the frontend as `errorUrl` in the return value of `loadData()`. Default: `checkout.htm`
`cancelTemplate`	string	Name of the shop template (view) that the customer is redirected to after canceling the PayPal payment (URL parameter `wsPaymentStatus=cancel`). Available in the frontend as `cancelUrl` in the return value of `loadData()`. Default: `checkout.htm`
`expressCheckoutAllow`	bool	Allows PayPal Express (direct-buy buttons, e.g. in the basket or on the product). Default: `false`
`expressCheckoutApplePayAllow`	bool	Allows Apple Pay Express via the PayPal Commerce Platform. Whether Apple Pay Express can be offered in the frontend is output by `$wsPayPalCheckout.expressCheckoutApplePay`.
`expressCheckoutGooglePayAllow`	bool	Allows Google Pay Express via the PayPal Commerce Platform. Whether Google Pay Express can be offered in the frontend is output by `$wsPayPalCheckout.expressCheckoutGooglePay`.

`payment.payPalCheckoutErrors` - Error texts for declined PayPal payments

If PayPal declines a payment or the shop’s check fails, the buyer returns to the checkout and sees the reason there. The payment.payPalCheckoutErrors node defines which text appears. Each decline reason reported by PayPal is assigned its own parameter. In addition, there are reasons from the shop’s own checks, which PayPal itself never reports. In the template, the reason is available under $wsCheckout.problems.clearing. The code property contains the name of the parameter, text the ready-made text from this node. If PayPal reports a reason for which there is no parameter here, the shop uses the general text from checkout.clearingErrors. Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden: https://<shop-domain>/admin/config/payment.payPalCheckoutErrors (Deeplink-Übersicht)

**Fehlertexte sind schreibgeschützt.** Die Fehlercode-Felder auf dieser Seite enthalten den Namen eines Textbausteins (ws.error.<configId>.<errorCode>), nicht den Fehlertext. Gepflegt wird der Text ausschließlich im Textbaustein-Dienst des Admin-Interface – Änderungen an der Konfiguration werden beim Speichern abgewiesen, auch über die [REST API](/schnittstellen/admin-interface-api/api-referenz-konfiguration). E-Mail-Vorlagen sind nicht betroffen.

Below is an excerpt from the configuration for payment.payPalCheckoutErrors:

{
  "errorCodes": {
    "cardExpired": "<Textbaustein>",
    "instrumentDeclined": "<Textbaustein>",
    "orderAmountMismatch": "<Textbaustein>",
    "threeDSecureFailed": "<Textbaustein>"
  }
}

Parameter description

All parameters are located under errorCodes and are of type string. Each parameter refers to a text snippet named ws.error.payPalCheckout.<Parameter>, for example ws.error.payPalCheckout.cardExpired. The table shows the German default text, translated into English. Dieser Text wird über einen Textbaustein realisiert.
Alles zu Textbausteinen in Konfigurationen finden Sie hier. Reasons reported by PayPal

Parameter	PayPal message	Default text
`applePayAmountMismatch`	`APPLE_PAY_AMOUNT_MISMATCH`	The Apple Pay amount does not match the order amount. Please try again.
`authorizationAmountExceeded`	`AUTHORIZATION_AMOUNT_EXCEEDED`	The authorized amount has been exceeded. Please contact your bank or choose another payment method.
`bankNotSupportedForVerification`	`BANK_NOT_SUPPORTED_FOR_VERIFICATION`	Your bank does not support the required verification. Please choose another payment method.
`bankVerificationRequired`	`BANK_VERIFICATION_REQUIRED`	Your bank requires additional verification. Please follow your bank’s instructions.
`billingAddressInvalid`	`BILLING_ADDRESS_INVALID`	The billing address provided is invalid. Please check your entry.
`cardBrandNotSupported`	`CARD_BRAND_NOT_SUPPORTED`	This card brand is not supported. Please choose another payment method.
`cardCountryNotSupported`	`CARD_COUNTRY_NOT_SUPPORTED`	Cards from this country are not supported. Please choose another payment method.
`cardDataNotFound`	`CARD_DATA_NOT_FOUND`	The card data could not be found. Please try again or choose another payment method.
`cardExpired`	`CARD_EXPIRED`	The card has expired. Please use another card.
`cardTypeNotSupported`	`CARD_TYPE_NOT_SUPPORTED`	This card type is not supported. Please choose another payment method.
`cityRequired`	`CITY_REQUIRED`	Please enter a city.
`complianceViolation`	`COMPLIANCE_VIOLATION`	The payment could not be processed for regulatory reasons.
`contingencyNotSuccessful`	`CONTINGENCY_NOT_SUCCESSFUL`	Payment authentication was not successful. Please try again or choose another payment method.
`countryNotSupportedByPaymentSource`	`COUNTRY_NOT_SUPPORTED_BY_PAYMENT_SOURCE`	Your country is not supported by this payment method. Please choose another payment method.
`currencyNotSupportedForBank`	`CURRENCY_NOT_SUPPORTED_FOR_BANK`	This currency is not supported by your bank. Please choose another payment method.
`currencyNotSupportedForCardType`	`CURRENCY_NOT_SUPPORTED_FOR_CARD_TYPE`	This currency is not supported by this card type. Please choose another payment method.
`domesticTransactionRequired`	`DOMESTIC_TRANSACTION_REQUIRED`	This card can only be used for domestic transactions. Please choose another payment method.
`ibanCountryNotSupported`	`IBAN_COUNTRY_NOT_SUPPORTED`	The country of this IBAN is not supported. Please choose another payment method.
`instrumentDeclined`	`INSTRUMENT_DECLINED`	The selected payment instrument was declined. Please choose another payment method or contact your bank.
`invalidExpiryDate`	`INVALID_EXPIRY_DATE`	The expiration date provided is invalid. Please check your entry.
`invalidIban`	`INVALID_IBAN`	The IBAN provided is invalid. Please check your entry.
`invalidPostalCode`	`INVALID_POSTAL_CODE`	The postal code provided is invalid. Please check your entry.
`invalidPostalCodeLength`	`INVALID_POSTAL_CODE_LENGTH`	The postal code provided has an invalid length. Please check your entry.
`invalidSecurityCodeLength`	`INVALID_SECURITY_CODE_LENGTH`	The security code entered has an invalid length. Please check your entry.
`payeeBlockedTransaction`	`PAYEE_BLOCKED_TRANSACTION`	The payment could not be completed. Please choose another payment method.
`payerAccountLockedOrClosed`	`PAYER_ACCOUNT_LOCKED_OR_CLOSED`	Your PayPal account is locked or closed. Please contact PayPal or choose another payment method.
`payerCannotPay`	`PAYER_CANNOT_PAY`	No payment can be made with this account. Please choose another payment method.
`payerNotSupportedByPaymentSource`	`PAYER_NOT_SUPPORTED_BY_PAYMENT_SOURCE`	Your account is not supported by this payment method. Please choose another payment method.
`paymentDenied`	`PAYMENT_DENIED`	The payment was declined. Please contact your bank or choose another payment method.
`paymentSourceCannotBeUsed`	`PAYMENT_SOURCE_CANNOT_BE_USED`	This payment instrument cannot be used. Please choose another payment method.
`paymentSourceDeclinedByProcessor`	`PAYMENT_SOURCE_DECLINED_BY_PROCESSOR`	The payment was declined by the payment service provider. Please choose another payment method.
`paymentSourceInfoCannotBeVerified`	`PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED`	The payment information could not be verified. Please check your entry or choose another payment method.
`postalCodeRequired`	`POSTAL_CODE_REQUIRED`	Please enter a postal code.
`preferredBrandNotSupported`	`PREFERRED_BRAND_NOT_SUPPORTED`	The preferred card brand is not supported. Please choose another payment method.
`puiDuplicateOrder`	`PUI_DUPLICATE_ORDER`	This order has already been processed. Please check your orders.
`referencedCardExpired`	`REFERENCED_CARD_EXPIRED`	The stored card has expired. Please update your payment details or choose another payment method.
`shippingAddressInvalid`	`SHIPPING_ADDRESS_INVALID`	The shipping address provided is invalid. Please check your entry.
`transactionBlockedByPayee`	`TRANSACTION_BLOCKED_BY_PAYEE`	The transaction was declined. Please choose another payment method.
`transactionLimitExceeded`	`TRANSACTION_LIMIT_EXCEEDED`	The transaction limit has been exceeded. Please contact your bank or choose another payment method.
`transactionReceivingLimitExceeded`	`TRANSACTION_RECEIVING_LIMIT_EXCEEDED`	The receiving limit for payments has been exceeded. Please try again later or choose another payment method.
`transactionRefused`	`TRANSACTION_REFUSED`	The transaction was refused. Please contact your bank or choose another payment method.

Reasons from the shop’s checks

Parameter	Trigger	Default text
`orderStateInvalid`	The PayPal order does not have a valid status when checked by the shop.	The PayPal payment could not be completed. Please try again.
`orderAmountMismatch`	The amount of the PayPal order differs from the basket.	The amount of the PayPal payment does not match your basket. Please start the payment again.
`threeDSecureFailed`	The 3-D Secure check of the card failed.	The 3D Secure check of your card failed. Please try again or choose another payment method.
`pendingPaymentDenied`	PayPal reports the payment as pending and `denyPendingPayments` is active under `payment.payPalCheckout`.	The PayPal payment could not be confirmed immediately. Please choose another payment method.
`captureOrderStatusInvalid`	During capture, the PayPal order has neither the status completed nor pending.	The PayPal payment could not be completed. Please try again or choose another payment method.
`captureDeclined`	PayPal completed the order but declined the capture of the amount.	The payment was declined by PayPal. Please choose another payment method.
`captureStatusUnknown`	The status of the capture cannot be determined.	The status of your PayPal payment could not be determined. Please check in your PayPal account whether the payment was made before trying again.

`payment.payPalPlus` - PayPal Plus configuration

PayPal Plus was an integrated payment solution for online merchants that bundled PayPal, direct debit, credit card, and purchase on account in one module. In the meantime, PayPal Plus has been replaced by the new PayPal Checkout. The integration has therefore been removed from the current software generation.The payment.payPalPlus node formerly configured PayPal Plus in the shop. This included, for example, activation, setting the mode (Live / test mode), and the language.Example configuration

{
  "active": false,
  "denyPendingPayments": true,
  "dummyProductAddition": "dummy product",
  "experienceProfileID": "<PROFILEID>",
  "merchantId": "<MERCHANTID>",
  "mode": "sandbox"
}

Parameter description

Parameter	Type	Description
`active` (coming soon)	bool	Enables / disables PayPal Plus.
`merchantId`	string	PayPal Merchant ID of the merchant account.
`dummyProductAddition`	string	Optional additional text for item names in case PayPal requires a minimum entry (e.g. placeholder for empty names).
`experienceProfileID`	string	ID of a PayPal Experience Profile (controls, among other things, display / branding in the PayPal flow).
`denyPendingPayments`	bool	`true` - orders with the PayPal status “pending” are rejected or not continued. `false` - “pending” is allowed.
`mode`	enum	Operating mode of PayPal Plus. `sandbox` - test mode `live` - production mode Default: `sandbox`

`payment.stripe` - Stripe configuration

The payment.stripe node configures Stripe as a payment service provider. This includes, for example, activation, setting the mode (Live / test mode), and the language. Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden: https://<shop-domain>/admin/config/payment.stripe (Deeplink-Übersicht)

Example configuration

{
  "active": false,
  "autoRefundOnError": true,
  "mode": "sandbox",
  "savedPaymentMethods": {
    "displaySavedPaymentMethods": false,
    "maxDisplayedSavedPaymentMethods": 3,
    "paymentMethodAllowDelete": false,
    "paymentMethodAllowSave": false
  },
  "targetAccount": ""
}

Parameter description

Parameter	Type	Description
`active`	bool	Enables / disables the Stripe connector.
`mode`	enum	Operating mode of Stripe. `sandbox` - test mode `live` - production mode Default: `sandbox`
`targetAccount`	string	Stripe account (e.g. account ID) to which payments are booked.
`autoRefundOnError`	bool	Enables automatic refund if an error occurs on the Websale side during order processing. Already paid but invalid orders are then automatically refunded. If the option is disabled, such cases must be refunded manually in Stripe. Default: `true`
`savedPaymentMethods`	object	Controls saved payment methods.
`displaySavedPaymentMethods`	bool	Show already saved payment methods in the checkout.
`maxDisplayedSavedPaymentMethods`	int	Maximum number of saved payment methods to display. Default: `3`
`paymentMethodAllowSave`	bool	Customers may save new payment means.
`paymentMethodAllowDelete`	bool	Customers may delete saved payment methods.

`payment.stripeErrors` - Error texts for declined Stripe payments

If Stripe declines a payment, the buyer returns to the checkout and sees the reason there. The payment.stripeErrors node defines which text appears. Each decline reason reported by Stripe is assigned its own parameter. The shop first evaluates Stripe’s exact decline reason (decline_code) and then the more general error code (code). In the template, the reason is available under $wsCheckout.problems.clearing. The code property contains the name of the parameter, text the ready-made text from this node. If Stripe reports a reason for which there is no parameter here, the shop uses the general text from checkout.clearingErrors. Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden: https://<shop-domain>/admin/config/payment.stripeErrors (Deeplink-Übersicht)

Below is an excerpt from the configuration for payment.stripeErrors:

{
  "errorCodes": {
    "cardDeclined": "<Textbaustein>",
    "expiredCard": "<Textbaustein>",
    "incorrectCvc": "<Textbaustein>",
    "insufficientFunds": "<Textbaustein>"
  }
}

Parameter description

All parameters are located under errorCodes and are of type string. Each parameter refers to a text snippet named ws.error.stripe.<Parameter>, for example ws.error.stripe.insufficientFunds. You can view the German default texts in the text snippet service. Dieser Text wird über einen Textbaustein realisiert.
Alles zu Textbausteinen in Konfigurationen finden Sie hier.

Parameter	Stripe message
`accountClosed`	`account_closed`
`amountTooLarge`	`amount_too_large`
`amountTooSmall`	`amount_too_small`
`approveWithId`	`approve_with_id`
`authenticationFailure`	`authentication_failure`
`authenticationRequired`	`authentication_required`
`bankAccountDeclined`	`bank_account_declined`
`bankAccountRestricted`	`bank_account_restricted`
`bankAccountUnusable`	`bank_account_unusable`
`callIssuer`	`call_issuer`
`cardDeclineRateLimitExceeded`	`card_decline_rate_limit_exceeded`
`cardDeclined`	`card_declined`
`cardNotSupported`	`card_not_supported`
`cardVelocityExceeded`	`card_velocity_exceeded`
`complianceViolation`	`compliance_violation`
`currencyNotSupported`	`currency_not_supported`
`debitNotAuthorized`	`debit_not_authorized`
`doNotHonor`	`do_not_honor`
`duplicateTransaction`	`duplicate_transaction`
`emailInvalid`	`email_invalid`
`expiredCard`	`expired_card`
`expiredPaymentInformation`	`expired_payment_information`
`expiredPaymentMethod`	`expired_payment_method`
`genericDecline`	`generic_decline`
`incorrectAddress`	`incorrect_address`
`incorrectCvc`	`incorrect_cvc`
`incorrectNumber`	`incorrect_number`
`incorrectPostalCode`	`incorrect_postal_code`
`incorrectZip`	`incorrect_zip`
`insufficientFunds`	`insufficient_funds`
`invalidAccount`	`invalid_account`
`invalidAmount`	`invalid_amount`
`invalidBillingAgreement`	`invalid_billing_agreement`
`invalidCustomerAccount`	`invalid_customer_account`
`invalidCvc`	`invalid_cvc`
`invalidExpiryMonth`	`invalid_expiry_month`
`invalidExpiryYear`	`invalid_expiry_year`
`invalidNumber`	`invalid_number`
`invalidPaymentInformation`	`invalid_payment_information`
`issuerNotAvailable`	`issuer_not_available`
`mobileDeviceAuthenticationRequired`	`mobile_device_authentication_required`
`newAccountInformationAvailable`	`new_account_information_available`
`noActionTaken`	`no_action_taken`
`notPermitted`	`not_permitted`
`partnerGenericDecline`	`partner_generic_decline`
`partnerHighRiskCustomer`	`partner_high_risk_customer`
`paymentIntentAuthenticationFailure`	`payment_intent_authentication_failure`
`paymentIntentPaymentAttemptExpired`	`payment_intent_payment_attempt_expired`
`paymentIntentPaymentAttemptFailed`	`payment_intent_payment_attempt_failed`
`paymentLimitExceeded`	`payment_limit_exceeded`
`paymentMethodCustomerDecline`	`payment_method_customer_decline`
`paymentMethodNotAvailable`	`payment_method_not_available`
`paymentMethodProviderDecline`	`payment_method_provider_decline`
`paymentMethodProviderTimeout`	`payment_method_provider_timeout`
`pickupCard`	`pickup_card`
`postalCodeInvalid`	`postal_code_invalid`
`processingError`	`processing_error`
`recurringNotSupportedByBank`	`recurring_not_supported_by_bank`
`reenterTransaction`	`reenter_transaction`
`referToCustomer`	`refer_to_customer`
`restrictedCard`	`restricted_card`
`revocationOfAllAuthorizations`	`revocation_of_all_authorizations`
`revocationOfAuthorization`	`revocation_of_authorization`
`securityViolation`	`security_violation`
`serviceNotAllowed`	`service_not_allowed`
`stopPaymentOrder`	`stop_payment_order`
`testmodeDecline`	`testmode_decline`
`transactionNotAllowed`	`transaction_not_allowed`
`withdrawalCountLimitExceeded`	`withdrawal_count_limit_exceeded`

`payment.transactionSettings` - Transaction settings (global)

The payment.transactionSettings node defines which actions can be performed in the store backend for payments, for example refunds, cancellations, status updates, or capturing the amount. For each payment provider, it is configured whether the respective action is allowed and which inputs are requested for it. Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden: https://<shop-domain>/admin/config/payment.transactionSettings (Deeplink-Übersicht)

Example configuration

{
  "clearers": [
    {
      "name": "paypalCheckout",
      "options": [
        { "name": "refund",  "active": true,  "additionalFields": [
          { "name": "amount",  "type": "decimal", "required": true },
          { "name": "reason",  "type": "string",  "required": false }
        ]},
        { "name": "cancel",  "active": true,  "additionalFields": [] },
        { "name": "refresh", "active": true,  "additionalFields": [] },
        { "name": "capture", "active": false, "additionalFields": [] }
      ]
    },
    {
      "name": "stripe",
      "options": [
        { "name": "refund",  "active": true,  "additionalFields": [
          { "name": "amount",     "type": "decimal", "required": false },
          { "name": "reference",  "type": "string",  "required": false }
        ]},
        { "name": "cancel",  "active": true,  "additionalFields": [] },
        { "name": "refresh", "active": true,  "additionalFields": [] },
        { "name": "capture", "active": true,  "additionalFields": [
          { "name": "amount", "type": "decimal", "required": true }
        ]}
      ]
    }
  ]
}

Parameter description

Parameter	Type	Description
`clearers`	list (object)	List of connected payment processors for which transaction settings should be configured.
`name`	string	Technical name of the provider (e.g. `paypalCheckout`, `stripe`).
`options`	list (object)	Defines the allowed actions and their input fields per provider.
`name`	enum	Possible options: `refund`, `cancel`, `refresh`, `capture`
`active`	bool	Enables / disables the action in the store backend.
`name`	string	Field name (e.g. `amount`)
`type`	string	Data type of the field (e.g. `string`, `int`).
`required`	bool	Defines whether it is a required field for the action.

`payment.*` - Validation and check services

The predefined validation and check services for the payment node are used in validations and services. An overview can be found here: Validation and check services The online clearing services referenced by the onlineClearing field of a payment method are also described on the Validation and check services page.

​payment* - Basic structure

​Parameter description

​payment.computopHosted - Computop Hosted Payments

​Example configuration (payment.computopHosted.creditcard)

​Parameter description

​payment.payment - Create payment methods

​Example configuration (payment.payment.paypalCheckout)

​Parameter description

​payment.paymentField - Additional fields for payment methods

​Example configuration (payment.paymentField.birthdatePayPal)

​Parameter description

​Multiple fields with the same name

​Remembering inputs

​Additional fields in the order data

​Example: PayPal purchase on invoice

​payment.payPalCheckout - PayPal Checkout configuration

​Example configuration

​Parameter description

​payment.payPalCheckoutErrors - Error texts for declined PayPal payments

​Parameter description

​payment.payPalPlus - PayPal Plus configuration

​payment.stripe - Stripe configuration

​Example configuration

​Parameter description

​payment.stripeErrors - Error texts for declined Stripe payments

​Parameter description

​payment.transactionSettings - Transaction settings (global)

​Example configuration

​Parameter description

​payment.* - Validation and check services

`payment*` - Basic structure

Parameter description

`payment.computopHosted` - Computop Hosted Payments

Example configuration (`payment.computopHosted.creditcard`)

Parameter description

`payment.payment` - Create payment methods

Example configuration (`payment.payment.paypalCheckout`)

Parameter description

`payment.paymentField` - Additional fields for payment methods

Example configuration (`payment.paymentField.birthdatePayPal`)

Parameter description

Multiple fields with the same name

Remembering inputs

Additional fields in the order data

Example: PayPal purchase on invoice

`payment.payPalCheckout` - PayPal Checkout configuration

Example configuration

Parameter description

`payment.payPalCheckoutErrors` - Error texts for declined PayPal payments

Parameter description

`payment.payPalPlus` - PayPal Plus configuration

`payment.stripe` - Stripe configuration

Example configuration

Parameter description

`payment.stripeErrors` - Error texts for declined Stripe payments

Parameter description

`payment.transactionSettings` - Transaction settings (global)

Example configuration

Parameter description

`payment.*` - Validation and check services