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": {},
    "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 the 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) 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 (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` = 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.

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.

Example configuration (`payment.payment.paypalCheckout`)

{
  "active": true,
  "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”.
`orderText` (coming soon)	text snippet (string)	Technical transfer value for connected third-party systems that is exported with the order.
`labels` (coming soon)	list / text snippet (string)	Optional short label for the payment method that can be shown 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, 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. 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.
`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.
`freeFields`	list (string)	Free fields (e.g. request additional info for purchase on account, such as date of birth or company info). Currently only used for Computop.

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

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. `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`
`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()`.
`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`). Available in the frontend as `errorUrl` in the return value of `loadData()`.
`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()`.
`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.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.

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.transactionSettings` - Transaction settings (global)

The payment.transactionSettings node defines which actions can be performed in the store backend for payments - e.g. refunds, cancellation, status update, or amount capture. 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 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

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