Created on: 2019-10-10 08:10 by

Wirecard CEE Integration Documentation

() -

Created: 2019-10-10 08:10

Online Guides - Integration documentation 1/18

 Created on: 2019-10-10 08:10 by
-

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.

Online Guides - Integration documentation 2/18

 Created on: 2019-10-10 08:10 by
-

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

Online Guides - Integration documentation 3/18

 Created on: 2019-10-10 08:10 by
-

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.

Online Guides - Integration documentation 4/18

 Created on: 2019-10-10 08:10 by
-

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)

Online Guides - Integration documentation 5/18

 Created on: 2019-10-10 08:10 by
-

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

Online Guides - Integration documentation 6/18

 Created on: 2019-10-10 08:10 by
-

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.

Online Guides - Integration documentation 7/18

 Created on: 2019-10-10 08:10 by
-

● 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

Online Guides - Integration documentation 8/18

 Created on: 2019-10-10 08:10 by
-

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.

Online Guides - Integration documentation 9/18

 Created on: 2019-10-10 08:10 by
-

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

Online Guides - Integration documentation 10/18

 Created on: 2019-10-10 08:10 by
-

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.

Online Guides - Integration documentation 11/18

 Created on: 2019-10-10 08:10 by
-

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

Online Guides - Integration documentation 12/18

 Created on: 2019-10-10 08:10 by
-

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

Online Guides - Integration documentation 13/18

 Created on: 2019-10-10 08:10 by
-

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

Online Guides - Integration documentation 14/18

 Created on: 2019-10-10 08:10 by
-

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.

Online Guides - Integration documentation 15/18

 Created on: 2019-10-10 08:10 by
-

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

Online Guides - Integration documentation 16/18

 Created on: 2019-10-10 08:10 by
-

COPlaceOrder – pipelines and logic for CreateOrder and PlaceOrder

Main scripts

Online Guides - Integration documentation 17/18

 Created on: 2019-10-10 08:10 by
-

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.

Online Guides - Integration documentation 18/18