Menu

User Tools

Create PDF

Site Tools


Wirecard Shop Plugin for Salesforce Commerce Cloud (Demandware)

Installation guide for Wirecard Checkout Page

This installation guide will show you the step-by-step installation of the plugin to your installed shop system on your web server. Please test your online shop and the configuration of the plugin on a test system, before you install the plugin on your production system.

Prerequisites

In order to integrate the Wirecard payment provider into your project make sure you have accomplished the following tasks:

  • You have access to and finished the setup of your Wirecard account. For more information contact your Wirecard partner manager, sales representative or support.
  • Your Wirecard account has been setup, and you have got your customer ID and pre-shared key (aka secret) to access it using the API.

Step 1: Installing the Wirecard Integration Cartridge

Please follow these initial steps to integrate the Wirecard integration cartridge to your project:

  1. Please import the int_wirecard cartridge in your Salesforce Commerce Cloud (Demandware) UX Studio and assign it to your server project so that it is uploaded to the server.
  2. Login to Business Manager.
  3. Adjust the cartridge path:
    1. Open “Administration” → “Sites” → “Manage Sites” and choose the site(s) in which you want to integrate the Wirecard payment service.
    2. Change to the “Settings” tab and add the int_wirecard cartridge, separated by colon (:), into your cartridge path.
    3. Go back to “Administration” → “Sites” → “Manage Sites” and choose the Business Manager site.
    4. Add the int_wirecard cartridge, separated by colon (:), into your cartridge path.
  4. Import the custom Site Preferences:
    1. Switch to “Site Development” → “Import & Export”
    2. Upload file Wirecard_system-objecttype-extensions.xml and import it afterwards. This file contains the necessary site preferences.
  5. Create or import the Payment Processors:
    1. Rename file Wirecard_payment-processors.xml to payment-processors.xml and add it into your site import package file or create a site import which just contains this file. Upload and import the site import file under “Administration” → “Site Development” → “Site Import & Export”.
    2. Alternately, create the payment processors manually in your “Site” → “Ordering” → “Payment Processors”
      1. Id: WIRECARD_CREDIT; Description: Wirecard credit card payment processor.
      2. Id: WIRECARD_EPS; Description: Wirecard EPS Onlineueberweisung payment processor.
      3. Id: WIRECARD_IDEAL; Description: Wirecard iDeal payment processor.
      4. Id: WIRECARD_PAYPAL; Description: Wirecard PayPal payment processor.
      5. Id: WIRECARD_SOFORT; Description: Wirecard Sofort. payment processor.
      6. Id: WIRECARD_SELECT; Description: Wirecard Select payment processor.
  6. Import the Wirecard Payment Methods:
    1. Select the site you want to integrate Wirecard, and go to “Ordering” → “Import & Export”.
    2. Upload file Wirecard_payment-methods.xml and import it as Payment Methods. Therefore, go to “Ordering” → “Import & Export” → “Payment Methods”, click Import and follow the import steps.
  7. Activate the “Fatal Error” notification (optional):
    1. Navigate to “Administration” → “Operations” → “Custom Log Settings”. Enter a list of e-mail addresses in the “Fatal” Receive Email input field.

Step 2: Specifying values for the site preferences

In Business Manager open your site, navigate to “Site Preferences” → “Custom Site Preferences” and choose the Wirecard preference group. This will open the preferences page where you see all required Site Preferences. Configure the settings as necessary:

Wirecard Preferences

  • Wirecard URL: Configuration value for the URL of the Wirecard server. The default value should already point to the correct server, but can be changed if necessary.
  • Customer ID: Enter the Wirecard customer ID you receive only for the Production system. The default values are for the generic test environment.
  • Secret String: Enter the Wirecard secret string / Pre-Shared key you receive only for the Production system. The default values are for the generic test environment.
  • Shop Id: Enter the value for the Shop ID, in order to indicate which premium templates should be loaded on their servers. You will receive this value from Wirecard.
  • Success URL: Indicates the pipeline which is called as Wirecard Success URL. The default value is already configured with the correct URL.
  • Cancel URL: Indicates the pipeline which is called as Wirecard Cancel URL. The default value is already configured with the correct URL.
  • Failure URL: Indicates the pipeline which is called as Wirecard Failure URL. The default value is already configured with the correct URL.
  • Confirm URL: Indicates the pipeline which is called as Wirecard Confirm URL. The default value is already configured with the correct URL.
  • Pending URL: Indicates the pipeline which is called as Wirecard Pending URL. The default value is already configured with the correct URL.
  • Service URL: Indicates the pipeline which is called as Wirecard Service URL. The default value is already configured with the correct URL. Note that the pipeline points to the default SG2 content page, and the ID of the content asset might be changed within the pipeline.
  • Display Text: Resource Bundle Key for the display text displayed on the Wirecard templates. The resource bundle file is part of the plugin.
  • Customer Statement: Resource Bundle Key for the Customer Statement Message. The resource bundle file is part of the plugin.
  • Order Description: Resource Bundle Key for the Order Description text displayed in Wirecard CEE Payment Center. The resource bundle file is part of the plugin.
  • Redirect Config: Controls if the Wirecard premium templates should be loaded in an iframe or within the browser window.
  • Submit Order Number: Defines if the value for order number will be submitted to Wirecard or not.
  • Duplicate Request Check: Defines if the Duplicate Request Check should be performed or not.

The following parameters are used as constants for the plugin, so please do not change the values of these parameters:

  • Trim Response Parameters: Defines if the response parameters are trimmed by Wirecard for the fingerprint calculation. Default is true.
    • Please note that this parameter is not implemented by Wirecard yet. Response parameter values are always trimmed by Salesforce Commerce Cloud (Demandware), and the value should always be set to true.
  • Shop Name: Shop name of identify the plugin at Wirecard. Default is ‘Salesforce Commerce Cloud’ and should not be changed.
  • Shop Version: Shop name of identify the plugin at Wirecard. Default is ‘17.2.0’ and might be changed per year.
  • Plugin Name: The internal Wirecard name of the plugin. There is no need to change the default value.
  • Plugin Version: The internal Wirecard version of the plugin. There is no need to change the default value.

Please make sure you have completed all settings for Sandboxes/Development, Staging and Production systems as necessary.

Step 3: Setting up and defining the payment methods

You can also control some preferences for the Wirecard payment methods. Therefore, please select your site and navigate to “Ordering” → “Payment Methods”. Within the list you find the following new payment methods:

  • WIRECARD_EPS_ONLINE_TRANSFER: EPS Onlineüberweisung (mainly used for Austria)
  • WIRECARD_IDEAL: iDeal (mainly used for the Netherlands)
  • WIRECARD_SOFORT_UEBERWEISUNG: Sofort. (mainly used for Germany)
  • WIRECARD_CREDIT_CARD: Credit Card
  • WIRECARD_PAYPAL: PayPal
  • WIRECARD_SELECT: When using this payment method in the shop, the consumer selects the payment method in the Wirecard Checkout Page. This has the advantage that you can use any payment method Wirecard is supporting without modifying the source code of your plugin or your online shop. Please contact our support teams to enable additional payment methods.

All payment methods are enabled by default, and should be disabled and sorted according to your needs.

You need to deactivate the Salesforce Commerce Cloud (Demandware) standard payment methods for CREDIT_CARD and PayPal.

The following custom attributes can be controlled for each payment method:

  • Wirecard Payment Type: The payment method string which is sent to Wirecard in the interface. The values are already configured for each payment method.
  • Wirecard Auto Deposit: Enables the autoDeposit option for Wirecard. It defines if a payment should be directly approved (authorized) and deposited (captured) in one single step. If set to false, the transaction will only be approved. This value is mainly used for Credit Card and PayPal transactions.
  • Wirecard Maximum Retries: Defines the number of maximum payment retries at Wirecard. If no value is defined, it won’t be submitted to Wirecard and a default parameter is used there.
  • Submit Shipping Data to Wirecard: Defines if the shipping address data are sent to Wirecard with the initial request. This value is only used for PayPal and has to be activated for this payment method.
  • Submit Billing Data to Wirecard: Defines if the billing address data are sent to Wirecard with the initial request. This value is only used for PayPal and has to be activated for this payment method.
  • Wirecard Update Shipping Data: Defines if the shipping address, which is returned by Wirecard, should overwrite the existing shipping address at the order. This value is only used for PayPal.

Step 4: Frontend changes and adjustments

Depending on your checkout process, you need at least to overwrite and design the following templates:

  • checkout/billing/paymentmethods.isml: This template lists the payment methods and fields in Site Genesis. The integration cartridge comes with an adjusted template which can be used in your storefront cartridge. It basically removes the standard credit card fields, and implements the logic to show only the “Select” payment method if it is activated. Styles should be moved to your project specific CSS file.
  • checkout/billing/wirecarderrormessage.isml: This template renders the error messages which are shown on the billing/payment page when Wirecard returns with a failure or the cancelUrl. The template can be included at the top of standard template checkout/billing/billing.isml.

  • checkout/confirmation/wirecardpendingpayment.isml: This template renders an error/warning message which is shown on the order confirmation page when Wirecard returns with a Pending payment code. The template should be included at the top of the standard template checkout/confirmation/confirmation.isml.

All Wirecard-related wording and error messages are stored within the integration cartridge in templates/default/resources/wirecard.properties, and can be changed according to your needs. Default messages are delivered in English and German.

For the texts which are sent to Wirecard (displayText, customerStatement, orderDescription), the order number can be used as a placeholder within the message.

Example:

Step 5: Necessary SG Controller Changes

A small change is necessary in the standard COPlaceOrder controller to ensure that the handlePayment function correctly redirects to Wirecard. Therefore, the ‘Handle’ hook returns a new result ‘redirected’ which the calling controller COPlaceOrder needs to evaluate correctly. The following changes have been made:

COPlaceOrder.handlePayments(): Return with ‘redirected: true’ – See lines 67ff in the screenshot below.

COPlaceOrder.start(): Add logic to return in function start(). See line 163ff in the screenshot below:

Furthermore, in order to ensure that the Wirecard redirect is tracked in Saleforce Commerce Cloud Analytics, you need to add a statement to controller COPlaceOrder-Start. The UUID of the basket needs to be mapped to a request custom parameter OriginalBasketUUID. The parameter is used in template wirecard/wirecardforward.isml to call the reporting hook. Changes to the number of the checkout step etc. need to be implemented in the project.

Main Scripts

WirecardManager: Main manager to handle the logic which is necessary for the integration. This is encapsulated in the following main functions:

  • getWirecardCallParameters(): Collects all required parameters to call Wirecard.
  • setWirecardPaymentParameters(): Sets all response parameters to the order and payment transaction depending on used the payment method.
  • validateWirecardAmountAndFingerprint(): Checks the Wirecard amount against the shop order amount and checks the fingerprint.
  • setOrderPaymentStatus(): Sets the order payment status to PAID only if the payment status is SUCCESS and the confirmation url was called.
  • checkAndRestoreBasket(): Checs if the basket has been restored when the order was set to failed, so after either the Cancel or Failure URL was called. Therefore, it is checked if the basket contains any line items (products or gift certificates). If a timeout is detected, it restores the basket and copies all line items, the billing and shipping address as well as the shipping method from the previously created order to the basket. Any copying of projectrelated custom attributes need to be added to this script.

WirecardLogger: Implements the custom logging for the cartridge.

Step 6: Script adjustments

When the cancelUrl, failureUrl or serviceUrl are called, the logic automatically detects a session timeout. Then, the basket will be restored from the previously created order using script wirecard/RestoreBasket.ds. You need to add the logic to copy any custom attribute from the order to the basket within this script. There are comments in the script for each business object which might be affected (shipping method, shipment, line item, shipping address and billing address).

Step 7: Testing the Wirecard integration

Once you completed the setup of the cartridge the integration needs to be tested against the Wirecard test system. The connection settings are already pre-configured in the custom site preferences.

All payment authorization processes, checks and forms are implemented on the Wirecard servers. When Wirecard responds with the successUrl or confirmUrl, all attributes are stored at the order and payment transaction if submitted and present in the response (see the list below). The values can be reviewed in “Business Manager” → “Select a Site” → “Ordering” → “Search and select an Order” → “Tabs: Attributes and Payment”.

Order attributes

  • Wirecard Order No: The internal order number or transaction returned by Wirecard. The value is stored at the order to search for these values in Business Managers and realize an easier operations process. Please note that this value is also stored as “transactionId” at the payment transaction object.

Payment transaction attributes

  • Wirecard Financial Institution: The financial institution.
  • Wirecard Gateway Reference Number: The gateway reference number.
  • Wirecard Contract Number: The contract number.
  • Wirecard Payment Method: The Wirecard internal payment method.
  • Wirecard Payment State: The Wirecard payment state (e.g. SUCCESS, PENDING, CANCEL).
  • Wirecard Masked PAN (Credit Card): The masked pan for the credit card. Only stored for credit card transactions.
  • Wirecard iDeal Consumer Name: The iDeal customer name.
  • Wirecard iDeal Consumer Account Number: The iDeal customer account number.
  • Wirecard iDeal Consumer City: The iDeal customer city.
  • Wirecard Sender Account Number (Sofortüberweisung): The account number used at Sofort.
  • Wirecard Sender Account Owner (Sofortüberweisung): The account owner who used Sofort.
  • Wirecard Sender Bank Number (Sofortüberweisung): The bank number which was used for the transfer at Sofort.
  • Wirecard Sender Bank Name (Sofortüberweisung): The bank name which was used for the transfer at Sofort.
  • Wirecard Sender BIC (Sofortüberweisung): The BIC code used for the transfer at Sofort.
  • Wirecard Sender IBAN (Sofortüberweisung): The IBAN used for the transfer at Sofort.
  • Wirecard Sender Country (Sofortüberweisung): The country code of the sender used at Sofort.
  • Wirecard Security Criteria (Sofortüberweisung): The security criteria returned by Sofort. Values are 0 (not secure) or 1 (secure), see the Wirecard documentation for more details.
  • Wirecard Paypal Payer Id: The payer ID of the customer who did the PayPal transaction.
  • Wirecard Paypal Payer Email: The e-mail address of the customer who did the PayPal transaction.
  • Wirecard Paypal Payer Last Name: The last name of the customer who did the PayPal transaction.
  • Wirecard Paypal Payer First Name: The first name of the customer who did the PayPal transaction.

Step 8: Customizations

You need to style and adjust the customization templates delivered by Wirecard with the integration package. The templates are not part of the plugin. Please refer to the documentation on how to adjust the templates, and e-mail them to our support teams once completed.

Wirecard will assign a shop ID, which you need to add as a site preference.

You can find more details regarding customizations of the Wirecard Checkout Page at Customization.

Step 9: Fraud handling

When the successUrl, pendingUrl or confirmUrl is called, the return values are checked as follows:

  • The order total amount at the order is the same as the authorized amount returned by Wirecard (success and confirmation only).
  • The returned fingerprint is valid.

If the check fails, a fatal error is logged to the Wirecard log scope. You may enable or disable to be informed about the fatal errors via e-mail in Business Manager at “Administration” → “Operation”s → “Custom Log Settings”.

Step 10: Go-live

Once all testing is done and the premium templates are setup, we recommend placing at least one test order per payment method against the live system of Wirecard, using real payment data. You can configure the settings on the Salesforce Commerce Cloud (Demandware) production system for that, or use the development system if necessary.

Additional implementation documentation

PendingUrl

The pendingUrl is called when Wirecard is not able to detect whether payment was successful or not. This might be the case for some payment methods such as e.g. PayPal. In this case, the standard behavior is to set the order state to ‘NEW’, but the payment status remains “NOT_PAID” and the wirecardPaymentState of the order is set to “PENDING”.

The order confirmation page is displayed to the customer and informs that the financial institution has not yet approved the payment and that confirmation will be sent later. Once the Wirecard payment state of the order is set to “SUCCESS”, the order is completed and the payment state is set to PAID.

Session timeouts

When there is a session timeout in Salesforce Commerce Cloud (Demandware), and the confirmUrl, successUrl or pendingUrl are called, there is no problem because the order is already created and will be set to state “NEW” within the pipeline. The customer might not be logged in anymore, but is still associated to the order.

When the cancelUrl, failureUrl or serviceUrl are called, the logic automatically detects a session timeout. Then, the basket will be restored from the previously created order using script RestoreBasket.ds. You need to add the logic to copy any custom attribute from the order to the basket within this script. The payment and eventually added gift certificates are not restored in the script and must be entered again.

Trimmed response parameter values – Fingerprint validation issues

The standard Salesforce Commerce Cloud (Demandware) platform removes all trailing and leading white-spaces for response parameter values. So in case a trailing white-space is sent back from Wirecard with one of the parameter values, the server logic will get this parameter without any white-space. In this case, the fingerprint calculation will fail, even if the payment is correct. The issue currently happens with the test interface of Sofort and a trailing white-space for parameter value “senderBankName”.

In order to avoid this in future, a parameter trimResponseParameters=yes is send to Wirecard, so that the parameters are also trimmed within the Wirecard Checkout Server to calculate the fingerprint. The parameter value can be controlled using a site preference and is already part of the integration.

Controllers

COWirecard: Main controller which implements all required storefront and backend logic. It contains all return URLs from Wirecard, the logic to handle the call to Wirecard, the rollback (failure) and completion of the order.

Payment hooks

WIRECARD_CREDIT et al.: These payment hooks are named as the payment methods, and contain three hook functions dynamically called by the SiteGenesis and Wirecard integration. The code is the same for all payment methods:

  • Handle: Called when the payment method is selected and adds the payment instrument to the basket.
  • Authorize: Jumps to COWirecard-Redirect which handles the collection of the call parameters.
  • Complete: Calls COWirecard-SetPaymentParameters to complete the payment and store all attributes.

The hooks are registered in file hooks.json as defined in the Site Genesis standard cartridge.

Main templates

wirecard/wirecardswitch: Implements the switch to decide if Wirecard should be opened in an iframe of the browser.

wirecard/wirecardforward: Submits the call parameters to Wirecard via post.

wirecard/wirecardresponse: Only called if Wirecard was opened in an iframe and responds within the iframe. The template posts all http parameters again to the top window, in order to avoid that the shop is loaded in the iframe again.

order/* : Business Manager hook templates for the “Order” → “Payment dialog” to print out all payment transaction fields and avoid error logs.

checkout/billing/* : See section Frontend Changes and Adjustments.

Installation guide for previous versions

If you use a previous version of Salesforce Commerce Cloud (Demandware) the following information may be of use for you.

Frontend Changes and Adjustment

In order to ensure that the Wirecard redirect is tracked in Salesforce Commerce Cloud Analytics, you should add an Assign node to pipeline COPlaceOrder-CreateOrder. The UUID of the basket needs to be mapped to a pipeline dictionary parameter OriginalBasketUUID. The parameter is used in template wirecard/wirecardforward.isml to call the reporting hook. Changes to the number of the checkout step etc. need to be implemented in the project.

Necessary pipeline call nodes

The Site Genesis 2 code supports the feature of “asynchronous payments” since version 13.1. The cartridge is build using this feature, but existing custom code can also be easily adapted if necessary.

Site Genesis 2 – Asynchronous payments integration

The cartridge should work as is and no pipeline modifications are necessary. The order is created in pipeline COPlaceOrder in state ‘CREATED’, and then the payment authentication is done. A dynamic pipeline node calls the “Authorize” pipeline for all Wirecard payment methods, which collects the necessary parameters and automatically posts this to Wirecard.

The error and cancel handling is implemented in the main plugin pipeline COWirecard, and set the order to ‘FAILED’ in this case. The basket will be restored in this case.

When the confirmUrl, successUrl or pendingUrl is called, all necessary attributes are stored at the order and payment. Pipeline COWirecard-SubmitImpl is called to complete the order and then the order confirmation page is shown.

Site Genesis 2 – Older versions (migration guide)

We strongly recommend to review the latest pipeline COPlaceOrder in the Site Genesis cartridge, and get familiar with the approach for asynchronous payments. The main changes you need to do in your project-specific pipeline COPlaceOrder are:

  • Please add a new pipeline “COPlaceOrder-CreateOrder” to create the order and use pipeline “CreateOrder2” (copy the code). Remove pipelet “CreateOrderNo”.
  • Adjust “COPlaceOrder-HandlePayments” to make dynamic call nodes to <payment-method-id>-Authorize, or add each single payment method you want to support.
  • Add a private call node for “COPlaceOrder-SubmitImpl”, which is called by the plugin.
  • Change “COPlaceOrder-PlaceOrder” and use pipelet “PlaceOrder” within there.
  • Additional changes for the authorization of gift certificates or similar might be necessary, but this strongly depends on your existing code.

COPlaceOrder – node for SubmitImpl

COPlaceOrder – pipelines and logic for CreateOrder and PlaceOrder

Main scripts

GetWirecardCallParameters: Collects all required parameters to call Wirecard.

SetWirecardPaymentParameters: Sets all response parameters to the order and payment transaction depending on used the payment method.

ValidateWirecardAmountAndFingerprint: Checks the Wirecard amount against the shop order amount and checks the fingerprint.

SetOrderPaymentStatus: Sets the order payment status to PAID only if the payment status is SUCCESS and the confirmUrl was called.

CheckSessionTimeout: This script checks if the basket has been restored when the order was set to failed, so after the either the cancelUrl or failureUrl was called. Therefore, it is checked if the basket contains any line items (products or gift certificates).

RestoreBasket: This script restores the basket and copies all line items, the billing and shipping address as well as the shipping method from the previously created order to the basket. Any copying of project-related custom attributes need to be added to this script.


This website uses cookies to deliver the best service to you. By continuing to browse the site, you are agreeing to our use of cookies.