> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# payment - Payment methods
> The payment node bundles the complete payment configuration: individual payment methods, display rules and providers such as PayPal, Stripe or Computop.
export const KonfigDeeplink = ({node}) => <>
You can open this setting directly in the Admin Interface via the following link:{" "}
{`https:///admin/config/${node}`}{" "}
(Deeplink overview)
;
export const TextbausteinHinweis = () => <>
Dieser Text wird über einen Textbaustein realisiert.
Alles zu Textbausteinen in Konfigurationen finden Sie{" "}
hier.
;
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
The basic structure of the `payment` node is shown below:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"payment": {
"payment": {},
"computopHosted": {},
"payPalCheckout": {},
"payPalPlus": {},
"stripe": {},
"transactionSettings": {}
}
}
```
#### Parameter description
| **Parameter** | **Description** |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `payment` | Controls which payment methods are offered in the shop. |
| `computopHosted` | Configures the connection to Computop. |
| `payPalCheckout` | Configures the connection to PayPal Checkout. |
| `payPalPlus` | Configures the connection to PayPal Plus. |
| `stripe` | Configures the connection to Stripe. |
| `transactionSettings` | Centrally defines which functions are supported by the payment providers
(e.g. `refund`, `manual`, `capturing`). |
***
## `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 language / template of the payment page.
#### Example configuration (`payment.computopHosted.creditcard`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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) to which Computop redirects the customer after payment. The return address is built from this template's URL; the outcome of the payment is appended as URL parameter `wsPaymentStatus` (`refresh` on success or `cancel` on cancellation). |
| `capturingMode` | enum | Allowed values:
`auto` = the payment is verified and collected directly in one step.
`manual` = the amount is only reserved during checkout but not yet charged. |
| `chDesc` | string | Text that appears for the payer (e.g. on the card statement). |
| `encryption` | enum | Allowed values:
`aes` = modern encryption option.
`blowfish` = older encryption option still supported. |
| `hmacKey` | string | Secret key for data integrity checks against Computop. |
| `hostedCheckBoxDefaultChecked` | bool | Sets a consent checkbox provided by Computop to active or inactive (`true` / `false`). |
| `hostedTemplateName` | string | Name of the template for the hosted Computop payment page. |
| `id` | string | Unique identifier of the payment method (e.g. `creditcard`). Freely selectable. |
| `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` = used in production. |
| `passCredentialOnFile` | bool | Marks "card data on file" for follow-up transactions, if supported. |
| `pwLarge` | string | Additional password according to Computop specification.
The password is used for encrypted transmission. |
| `sendIPAddr` | bool | Sends the customer 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 / discount in currency units on the total sum of the payment method (e.g. `0.30`).
`0` = no surcharge / discount.
Only possible if `capturingMode` is `manual`. |
| `uid` | string | Merchant / account ID at Computop. |
***
## `payment.payment` - Define payment methods
The `payment.payment` node combines all payment methods of the shop. Here you can define, for example, whether a payment method is active, how it should be named and presented in the checkout, which provider serves it and which rules apply.
#### Example configuration (`payment.payment.paypalCheckout`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": true,
"availableByDefault": true,
"basicCost": [
{ "subtotal": 0, "cost": 2.5 },
{ "subtotal": 50, "cost": 0 }
],
"description": "",
"discount": 0,
"displayedPaymentTypes": null,
"freeFields": null,
"id": "paypalCheckout",
"image": "",
"labels": [""],
"name": "",
"onlineClearing": {
"options": {
"view": "paypal_checkout_pending.htm"
},
"service": "payment.paypal-checkout"
},
"orderText": "",
"provider": "",
"type": "",
"validations": [
{ "service": "paymentValidation.voucherDeny" }
]
}
```
#### Parameter description
| **Parameter** | **Type** | **Description** |
| ------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active` | bool | Turns the payment method in the checkout on / off. |
| `availableByDefault` | bool | Controls whether the payment method is available to all customers by default (default: `true`).
If set to `false`, the payment method is not available to guests or regular customer accounts. It can then be enabled selectively for individual customer accounts by adding it to the account's `enabledPaymentMethods` list via the Admin API (see [API reference customer data](/en/schnittstellen/admin-interface-api/api-referenz-kundendaten)).
Conversely, a payment method that is 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` | Textbaustein (string) | Display name in the checkout, e.g. "PayPal".
|
| `orderText` (**coming soon**) | Textbaustein (string) | Technical handover value for connected third-party systems exported with the order.
|
| `labels` (**coming soon**) | list / textbaustein (string) | Optional short label for the payment method that can be displayed as a hint in the checkout.
|
| `type` (**coming soon**) | string | Describes the type of payment processing and helps with the display in the checkout.
Common values are: `online` — payment runs via a provider. `offline` — payment is handled manually. |
| `onlineClearing` | singleService | Links the payment method to a specific online payment engine and thus activates the real-time payment flow.
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) | Cost of the payment method, tiered by the basket subtotal. 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. The cost feeds into [`$wsCheckout.sum.paymentCost`](/en/frontend/referenz/module/wscheckout#wscheckout-sum) in the checkout. |
| `displayedPaymentTypes` | list (object) | This parameter allows you to store multiple entries with their own name, icon, image or description for a payment method.
This is particularly relevant when, for example, payment providers like Stripe are directly configured as payment methods but the contained payment options are to be presented separately outside of the order process — for example in the footer or on a payment methods information page.
The display of the contained payment options within the order process 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](/en/frontend/referenz/module/wsconfig), through which the configured entries can be displayed in the frontend at the desired position. |
| `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 under: [Validation and check services](/en/konfiguration/validierungs-und-prufservices). Target: `paymentValidation` |
| `discount` (**coming soon**) | float | Discount / surcharge in currency units (e.g. `2.00` — customer pays €2 less with this payment method). |
| `description` | Textbaustein (string) | Longer description / notes about the payment method.
|
| `longDescription` | Textbaustein (string) | Even more detailed variant of the description text than `description`, for example for a payment methods information page or detailed notes.
|
| `freeFields` | list (string) | Free fields (e.g. to capture additional information for invoice purchase, such as date of birth or company details).
Currently used only for Computop. |
***
## `payment.payPalCheckout` - PayPal Checkout configuration
The `payment.payPalCheckout` node configures the PayPal Checkout in the shop. This includes, for example, activation, the operating mode (live / test mode) and the language.
#### Example configuration
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 | Turns PayPal Checkout on / off. |
| `payerId` | string | PayPal merchant ID of the merchant account. |
| `dummyProductAddition` | string | Optional additional text for item names if PayPal requires a minimum input (e.g. placeholder for empty names). |
| `denyPendingPayments` | bool | `true` — orders with the PayPal status "**pending**" are rejected or not continued.
`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 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` |
| `approvalTemplate` | string | Name of the shop template (view) to which the customer is redirected after successful confirmation of the PayPal payment. The return address is built from this template's URL, with the URL parameter `wsPaymentStatus=refresh`. In the frontend it is available as `approvalUrl` or `expressApprovalUrl` in the return value of [`$wsPayPalCheckout.loadData()`](/en/frontend/referenz/module/wspaypalcheckout#wspaypalcheckout-loaddata). |
| `errorTemplate` | string | Name of the shop template (view) to which the customer is directed when an error occurs in the PayPal SDK (URL parameter `wsPaymentStatus=error`). Available in the frontend as `errorUrl` in the return value of `loadData()`. |
| `cancelTemplate` | string | Name of the shop template (view) to which the customer is directed after cancelling the PayPal payment (URL parameter `wsPaymentStatus=cancel`). Available in the frontend as `cancelUrl` in the return value of `loadData()`. |
| `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 indicated by [`$wsPayPalCheckout.expressCheckoutApplePay`](/en/frontend/referenz/module/wspaypalcheckout#wspaypalcheckout-expresscheckoutapplepay). |
| `expressCheckoutGooglePayAllow` | bool | Allows Google Pay Express via the PayPal Commerce Platform. Whether Google Pay Express can be offered in the frontend is indicated by [`$wsPayPalCheckout.expressCheckoutGooglePay`](/en/frontend/referenz/module/wspaypalcheckout#wspaypalcheckout-expresscheckoutgooglepay). |
***
## `payment.payPalPlus` - PayPal Plus configuration
**PayPal Plus** was an integrated payment solution for online merchants that bundled PayPal, direct debit, credit card and invoice purchase in one module. In the meantime, PayPal Plus has been replaced by the new [**PayPal Checkout**](/en/frontend/referenz/module/wspaypalcheckout). The integration has therefore been removed from the current software generation.
The `payment.payPalPlus` node used to configure PayPal Plus in the shop. This included, for example, activation, the operating mode (live / test mode) and the language.
**Example configuration**
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": false,
"denyPendingPayments": true,
"dummyProductAddition": "dummy product",
"experienceProfileID": "",
"merchantId": "",
"mode": "sandbox"
}
```
**Parameter description**
| **Parameter** | **Type** | **Description** |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `active` (**coming soon**) | bool | Turns PayPal Plus on / off. |
| `merchantId` | string | PayPal merchant ID of the merchant account. |
| `dummyProductAddition` | string | Optional additional text for item names if PayPal requires a minimum input (e.g. placeholder for empty names). |
| `experienceProfileID` | string | ID of a PayPal experience profile (controls, among other things, presentation / 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 PayPalPlus.
`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, the operating mode (live / test mode) and the language.
#### Example configuration
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": false,
"autoRefundOnError": true,
"mode": "sandbox",
"savedPaymentMethods": {
"displaySavedPaymentMethods": false,
"maxDisplayedSavedPaymentMethods": 3,
"paymentMethodAllowDelete": false,
"paymentMethodAllowSave": false
},
"targetAccount": ""
}
```
#### Parameter description
| **Parameter** | **Type** | **Description** |
| --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `active` | bool | Turns the Stripe connector on / off. |
| `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 the automatic refund if an error occurs during order processing on the WEBSALE side.
Orders that have already been paid but are invalid are automatically refunded.
If the option is disabled, such cases must be refunded manually in Stripe.
Default: `true` |
| `savedPaymentMethods` | object | Control of the stored payment methods. |
| `displaySavedPaymentMethods` | bool | Display already stored payment methods in the checkout. |
| `maxDisplayedSavedPaymentMethods` | int | Maximum number of stored payment methods to be displayed.
Default: `3` |
| `paymentMethodAllowSave` | bool | Customers are allowed to save new payment methods. |
| `paymentMethodAllowDelete` | bool | Customers are allowed to delete stored payment methods. |
***
## `payment.transactionSettings` - Transaction settings (global)
The `payment.transactionSettings` node defines which actions can be carried out in the store backend for payments — e.g. refunds, cancellation, updating the status or capturing the amount.
For each payment provider it is configured whether the respective action is allowed and which inputs are requested for it.
#### Example configuration
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 are to be configured. |
| `name` | string | Technical name of the provider (e.g. `paypalCheckout`, `stripe`). |
| `options` | list (object) | Defines per provider the allowed actions and their input fields. |
| `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](/en/konfiguration/validierungs-und-prufservices)