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

The basic structure of the payment node is shown below:

{
  "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`)

{
  "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`)

{
  "active": true,
  "availableByDefault": true,
  "basicCost": [
    { "subtotal": 0, "cost": 2.5 },
    { "subtotal": 50, "cost": 0 }
  ],
  "description": "<Textbaustein>",
  "discount": 0,
  "displayedPaymentTypes": null,
  "freeFields": null,
  "id": "paypalCheckout",
  "image": "",
  "labels": ["<Textbaustein>"],
  "name": "<Textbaustein>",
  "onlineClearing": {
    "options": {
      "view": "paypal_checkout_pending.htm"
    },
    "service": "payment.paypal-checkout"
  },
  "orderText": "<Textbaustein>",
  "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). 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` 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, 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. 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

{
  "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()`.
`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`.
`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`.

`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. 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

{
  "active": false,
  "denyPendingPayments": true,
  "dummyProductAddition": "dummy product",
  "experienceProfileID": "<PROFILEID>",
  "merchantId": "<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

{
  "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

{
  "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

​payment* - Basic structure

​Parameter description

​payment.computopHosted - Computop Hosted Payments

​Example configuration (payment.computopHosted.creditcard)

​Parameter description

​payment.payment - Define payment methods

​Example configuration (payment.payment.paypalCheckout)

​Parameter description

​payment.payPalCheckout - PayPal Checkout configuration

​Example configuration

​Parameter description

​payment.payPalPlus - PayPal Plus configuration

​payment.stripe - Stripe configuration

​Example configuration

​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` - Define payment methods

Example configuration (`payment.payment.paypalCheckout`)

Parameter description

`payment.payPalCheckout` - PayPal Checkout configuration

Example configuration

Parameter description

`payment.payPalPlus` - PayPal Plus configuration

`payment.stripe` - Stripe configuration

Example configuration

Parameter description

`payment.transactionSettings` - Transaction settings (global)

Example configuration

Parameter description

`payment.*` - Validation and check services