worldline Direct
Sign up

Introduction

Our SAP Commerce Cloud plug-in comes with regular updates and full integration support, offering a versatile out-of-the-box solution to accept online payments easily:

  • Offers the following payment methods on our platform:
    Alipay+
    American Express
    Apple Pay
    Bancontact
    Bizum
    Carte Bancaire
    Cpay
    Diners Club
    iDEAL
    Illicado
    Intersolve
    JCB
    Maestro
    MasterCard
    Multibanco
    OneyBrandedGiftCard
    PayPal
    SEPA Direct Debit
    Visa
    WeChat Pay
  • Manages multiple stores.
  • Accepts payment operations (Refunds, authorisations, captures etc.) directly from your SAP Commerce Cloud Backoffice.

Keep an eye on our Release Notes to stay informed about updates and new features (i.e. payment methods, features, integration modes) we have added to this plugin!

Check out our documentation to learn how to link your store with our platform to profit from all these features!

Download plugin
  • Entrust a system administrator with the installation and the configuration of the plugin.
  • Accordingly, the target audience of this documentation are system administrators with a profound knowledge of SAP Commerce Cloud / Hybris.

To process transactions with this plugin, you need an account on our platform.

This plugin works with both our test and live environment. A test account is a great way to get familiar with both the plugin and our platform. Once you want to go live, create a production account or contact us!

Install plugin

The first step to use the plugin is the installation process. Before you proceed, make sure your infrastructure meets these system requirements:

Item Description
Plugin package

Download the plugin

Direct credentials
Java

At least version 17, SapMachine 17 is recommended

JAVA_HOME property will need to be set to the correct location for the installer to work correctly

SAP Commerce

Officially supported versions of SAP Commerce cloud are:

  • 2211.2

Other patch releases of 2105 and 2011 are compatible with this plugin. However, the plugin is untested for other versions.
You will need to source a copy of SAP Commerce, as it is not included with the plugin.

SAP Commerce components

The reference storefront implementation is designed to work with the Apparel Accelerator.

Use with the B2B Accelerator, Electronics Accelerator or others is not officially supported. However, the backend services are in place to facilitate this.

If you have already customized your system heavily, some additional integration may be required, as this plugin is designed to work with the standard Accelerator UI.

Development environment

The examples in this document work with a UNIX-based development environment (e.g. Mac OS X or Linux).

For Windows installations, use the appropriate Windows commands (e.g. setantenv.bat, hybrisserver.bat).

PCI compliancy

SAQ A

The plugin’s in-built features ensure this security level, but you still need to get the certificate from your acquirer.

On top of these prerequisites, make sure to respect the extension structure:

Property Description
worldlinedirectb2ccheckoutaddon Contains the storefront modifications required to facilitate the injection of the Worldline Online Payments Direct payment journeys into the B2C Apparel Storefront Checkout Journey.
worldlinedirectbackoffice Contains Backoffice modifications to facilitate configuration of the plugin.
worldlinedirectcore Contains any data model additions and functional services which use our REST API. Also includes the Java SDK.
worldlinedirectcustomersupportbackoffice Contains modifications to the Customer Support Backoffice perspective which allow a Customer Support agent to manually capture or refund a transaction.
worldlinedirectfulfillmentprocess Contains modifications to the Out of the Box SAP Commerce order fulfillment Business Process. It allows you to control whether the system waits for a transaction to be authorised/captured before delivering the goods/services to your customers.
worldlinedirectocc Contains enhancements to the Omni Commerce Connect REST APIs included with SAP Commerce: You can process payments from a headless storefront or mobile app.
worldlinedirectwebhook Contains an endpoint for transaction status updates from our platform via webhooks.

This installation process applies to either:

  • a brand-new project with a standard.
  • out of the box accelerator storefront.
  • an existing project with its own storefront extension based on yacceleratorstorefront.

Once done, follow these steps:

1. Install SAP Commerce using ‘cx’ Recipe

SAP provides instructions for using the installation recipes in the SAP Help Portal. If you are unfamiliar with the general installation process, make sure to read through this before the installation.

You will require an existing installation of SAP Commerce to use the plugin. If you already have an installation of SAP Commerce with the B2C Accelerator and its corresponding extensions included, skip this step.

  • Download SAP Commerce in .Zip format. Unzip the platform and navigate to the ‘installer’ directory.
  • Run the following command: Replace ‘your_password’ with your desired administrator password for the system.
./install.sh -r cx -A local_property:initialpassword.admin=your_password
  • Run the following to build and initialise the system:
./install.sh -r cx initialize -A local_property:initialpassword.admin=your_password
hybris/
           config/
bin/
custom/
worldline/
  • The config directory contains a sample set of configurations in the local.properties file. Copy these configurations into the local.properties file generated after the SAP Commerce installation.
  • The config directory also contains a localextensions.xml file. Add the following from this file to your own localextensions.xml file that was generated after the SAP Commerce installation:

<!-- WORLDLINE -->
<extension dir="${HYBRIS_BIN_DIR}/custom/worldline/worldlinedirectcore"/>
You will require an existing installation of SAP Commerce in order to be able to use the Worldline Direct
plugin. If you already have an installation of SAP Commerce with the B2C Accelerator and its
corresponding extensions included, you can skip this step.
Worldline – SAP Commerce Cloud Documentation
Technical Documentation – 9
<extension dir="${HYBRIS_BIN_DIR}/custom/worldline/
worldlinedirectb2ccheckoutaddon"/>
<extension dir="${HYBRIS_BIN_DIR}/custom/worldline/worldlinedirectbackoffice"/>
<extension dir="${HYBRIS_BIN_DIR}/custom/worldline/worldlinedirectocc"/>
<extension dir="${HYBRIS_BIN_DIR}/custom/worldline/worldlinedirectwebhook"/>
<extension dir="${HYBRIS_BIN_DIR}/custom/worldline/
worldlinedirectcustomersupportbackoffice"/>
<extension dir="${HYBRIS_BIN_DIR}/custom/worldline/
worldlinedirectfulfilmentprocess"/>

You should examine each extension’s extensioninfo.xml file (contained within the root of each extension’s directory) to ensure the extensions mentioned within each <requires-extension> tag are included in your localextensions.xml.

  • The bin/custom/worldline directory contains all required extensions. Copy them into your own hybris/bin/custom/worldline directory. If you wish to put these extensions in a different directory, update your localextensions.xml accordingly.

2. Install Extension to Storefront

  • You may need to run the following command to ensure the correct addons are available in your storefront:


  
   ant addoninstall
   
-Daddonnames=
"adaptivesearchsamplesaddon,assistedservicecustomerinterestsaddon,assistedserviceprom
otionaddon,assistedservicestorefront,assistedserviceyprofileaddon,captchaaddon,config
urablebundleaddon,consignmenttrackingaddon,customercouponaddon,customercouponsamplesa
ddon,customerinterestsaddon,customerticketingaddon,eventtrackingwsaddon,merchandising
addon,merchandisingstorefrontsampledataaddon,multicountrysampledataaddon,notification
addon,ordermanagementaddon,orderselfserviceaddon,pcmbackofficesamplesaddon,personaliz
ationaddon,personalizationsampledataaddon,personalizationyprofilesampledataaddon,prof
iletagaddon,selectivecartsplitlistaddon,smarteditaddon,stocknotificationaddon,textfie
ldconfiguratortemplateaddon,timedaccesspromotionengineaddon,timedaccesspromotionengin
esamplesaddon,xyformssamples,xyformsstorefrontcommons,ysapproductconfigaddon"
-DaddonStorefront.yacceleratorstorefront="<YOUR-STOREFRONT>"


Replace <YOUR-STOREFRONT> with your storefront extension’s name, e.g. yacceleratorstorefront or <project>storefront

To run the ant commands below, you will need to run . ./setantenv.sh or its Windows equivalent within the hybris/bin/platform directory.

  • Install the Addon to your Storefront, use the following command:
ant addoninstall -Daddonnames="worldlinedirectb2ccheckoutaddon"
-DaddonStorefront.yacceleratorstorefront="<YOUR-STOREFRONT>"
  • Now rebuild your system:
ant clean all
  • Perform either an initialisation or system update. You can do both via the Hybris Administration Console (HAC) at https://<your-server>:9002/hac or you can initialize this via the ant target:
ant initialize

Configure plugin

After the installation, you need to configure the plugin to link your store to our platform.

This section of the documentation will cover technical configuration elements only. For business configuration within the SAP Backoffice, check this section.

Configure properties

  • From worldlinedirectcore/project.properties :
worldline.direct.api.authorizationType=V1HMAC
worldline.direct.api.connectTimeout=10000
worldline.direct.api.socketTimeout=10000
worldline.direct.api.maxConnections=10
worldline.direct.api.integrator=Worldline


The Java SDK passes these configurations and controls the connectivity. Have a look at our dedicated Java SDK documentation for more information.

  • From worldlinedirectbackoffice/project.properties:
worldline.contact.support.default.cc=
worldline.contact.support.default.bcc=
worldline.contact.support.default.subject=default subject


These configurations control the button within the SAP Back Office which is used to contact us for support via email.

  • From worldlinedirectocc/project.properties:
worldline.occ.hostedCheckout.returnUrl=https://localhost:9002/occ/v2/%s/users/%s/orders/%s/hostedcheckout
worldline.occ.hostedTokenization.returnUrl=https://localhost:9002/occ/v2/%s/users/%s/orders/%s/hostedtokenization/return3ds


These configurations set the value for the Server API’s property HostedCheckoutSpecificInput.ReturnUrl to ensure your customers correct redirection to your webshop environment. It is important to update these values to reflect your system’s URL.

Configure Webhooks

The plugin uses webhooks to get the current status of your transactions from our platform. SAP Commerce uses the endpoint /worldline/webhook to receive these status updates.

Configure a WebhooksKey, WebhooksKeySecret and Endpoint URLs in your PSPID as described in our dedicated guide. Make sure the URL:

  • Contains your site’s hostname '(i.e. https://<your-domain>:9002/worldline/webhook)'
  • Has a valid SSL certificate

Configure SAP

The following steps cover the configuration process of the SAP Commerce Backoffice tool. For general information about the SAP Commerce Backoffice, refer to the Business User guides in the SAP Help Portal.

After the successful installation, the SAP Backoffice contains a new item type “Worldline Configuration”. Follow these steps to link your Base Store in SAP Commerce to our platform:

  • Login to the SAP Commerce Backoffice via the default URL https://<hostname>:9002/backoffice. Default administrator credentials will have been defined during installation or provided to you separately.

Go to Worldline > Worldline Configuration. Click on the “+” – symbol in the taskbar.

The image above shows where to find the Worldline Configuration item and the “+” symbol in the taskbar
  • Enter the following from the table in the appearing pop-window:
Property Description/Actions
API Key Enter the API key of your test or live PSPID. Read our dedicated guide to learn how to generate one.
API Secret Enter the API secret of your test or live PSPID. Read our dedicated guide to learn how to generate one.
Ask Consumer Consent Configure this in the following step.
Enforce SCA Set Enforce Strong Customer Authentication to Yes or No. We strongly recommend setting it to YES to avoid a high rate of declined transactions.
Endpoint URL

The test or live endpoint on our platform. Copy them from our dedicated guide.

  • Read our dedicated guides about API endpoints and authentication to get a thorough understanding about the test/live environment and API key/API secret.
  • Make sure not to mix up credential from test with live and vice versa.
  • Make sure to switch to the LIVE-URL as soon as you have finalised your tests.
SCA Exemption

Some markets allow you to potentially exempt your customers from a 3-D Secure check. Set Exemption for transactions under 30 EUR to Yes or No.
Visible only if "Enforce SCA" is false.

First recurring payment

Indicate whether to fully charge your customers for the first order in a serious of multiple orders.
True: Charge the first order.
False: Do noot charge the first order.

Grouped cards

Define whether to group all card payment methods on the Hosted Checkout Page.

Split order level promotion to line items

Define whether your system will attempt to apportion Order Level Promotions across the individual order lines when sending an order to our platform.

We strongly recommended YES if you are using order level promotions in your SAP Commerce system.

Merchant ID Enter the PSPID on our platform you want to use for transaction processing.
webhookKeyId Enter the webhookKeyId of your test or live PSPID from the previous step.
webhookSecret Enter the webhookSecret of your test or live PSPID from the previous step.

Click on "DONE" to confirm your configuration

  • Click on the configuration profile in the table you have just confirmed. Enter the following from the table overview:
Property Description/Actions
OPERATION CONFIGURATION
  • Operation Code: Define whether to process the transactions as authorisation mode or as direct sale. Select one of the following options:
    • Authorization: the amount is only blocked on your customer's card. Successful transactions will have StatusCode=5 (this is used when you wish to capture a transaction only after shipping the article)
    • Sale: the amount has been ordered to be paid out in one go. Successful transactions will have StatusCode=9
  • Capture Time Frame: Set a capture delay for authorised transactionof X days. At the end of this duration, a cron job will capture the transaction automatically. If the transaction is partially captured already in the meantime, any available funds that remain will be captured.

If "Operation Code" is set to "Authorization", beware of the following:

  • Make sure that you capture authorised transaction later. Only then will the transaction reach statusCode=9, for which you receive the actual payment for the transaction.
  • Even if the "Capture Delay" is set to X days, you can also manually capture funds fully/partially by opening an individual order once you have delivered the goods/services.
  • Session Timeout: Define the duration of a customer session for adding payment details. If undefined, the duration is 180 minutes. Only applicable for transactions processed via Hosted Tokenization Page.
TOKENIZATION CONFIGURATION
  • Ask Consumer Consent: Define whether your customers must opt-in/opt-out for permanent Token creation.
  • Tokenization Template: If you process transactions via our Hosted Tokenization Page, enter the file name of your template to adapt the iframe to the look and feel of your shop.

     To learn how to create templates, see our dedicated chapter in Hosted Tokenization Page guide.

3DS CONFIGURATION
  • Enforce SCA: Define whether to enforce Strong Customer Authentication. We strongly recommend setting it to YES to avoid a high rate of declined transactions.
  • SCA Exemption: Some markets allow you to potentially exempt your customers from a 3-D Secure check. Set Exemption for transactions under 30 EUR to Yes or No.
    Visible only if "Enforce SCA" is false.
GROUPED CARDS CONFIGURATION
  • Grouped cards: Define whether to group all card payment methods on the Hosted Checkout Page.
  • Grouped Cards icon: Add a SAP CC media file to display a cards label. 
RECURRING PAYMENTS CONFIGURATION
  • Replenishment number of retries on failure: Define the number of allowed retries for failed payments for subsequent orders. Default value: 5.
  • Indicate whether to fully charge your customers for the first order in a serious of multiple orders.
    True: Charge the first order.
    False: Do noot charge the first order.
OTHER CONFIGURATIONS
  • Split Order Level Promotion to Order Line Items: Define whether your system will attempt to apportion Order Level Promotions across the individual order lines when sending an order to our platform.

    We strongly recommended YES if you are using order level promotions in your SAP Commerce system.


Click on “SAVE” to confirm your configuration.

Configure Base store

Before you start processing (test) transactions, you need to

To do so, follow these steps and confirm by clicking "SAVE" in each tab:

  • Go to Base Commerce > Base Store. Select the store from the table with headers "ID" / "Name".

Select "Worldline" from the available tabs and scroll down to "WORLDLINE CONFIGURATION".

The image above shows where to find the "WORLDLINE" tab.
  • Enter the following from the table overview:
Property Description/Actions
Payment Provider Configuration

Associates your base store with a configuration profile.

Click on the field to select the configuration profile you set up in the previous steps.

Checkout type

Select an integration mode for transaction processing.

If you choose "Hosted Tokenization", make sure to configure a template via Worldline > Worldline Configuration.

Do not switch between checkout modes whilst the site is live, as this might lead to undesirable effects on your customers' payment journey.

Checkout type Description/Actions
Hosted Tokenization

All card brands bundled together in a single iFrame on your checkout page itself via our Hosted Tokenization Page.
Your customers stay on your checkout page while entering their card details in an iframe hosted on our server. The iframe presents a single payment method "Credit card" which autodetects the card brand based on card number input.

Read our dedicated guide about Hosted Tokenization Page to leanr more about this integration mode.

Bancontact is available only on Hosted Checkout Page in QR code mode.

Hosted Checkout

Each card brand listed individually for redirect upon selection to our Hosted Checkout Page.

All card brands are listed individually on your checkout page. Upon selection of the brand, the plugin redirect your customers to our Hosted Checkout Page to enter their card credentials for the selected brand.

Read our dedicated guide about Hosted Checkout Page to leanr more about this integration mode.

Merchant Email

Define the sender e-mail address your customers will receive updates from about updates for to their replenishment orders.

  • Select "ADMINISTRATION" from the available tabs and scroll down to "UNBOUND". Enter "worldlineB2CResponsiveCheckoutGroup" in field "Checkout Flow Group"
  • Select "PROPERTIES" from the available tabs and scroll down to "PAYMENT PROVIDER". Enter "Worldline" in field "Payment Provider"
The image above shows where to find the “PROPERTIES” and the "ADMINISTRATION" tab.

Test connection

Once you have completed all the steps, verify the configuration by establishing a test connection between the plugin and our platform:

  • Go to Worldline > Worldline Configuration. Select the configuration profile from the table with headers "Merchant ID" / "API Key".
  • Click on "Test connection" in the configuration profile overview. Check that the appearing pop-up window states "OK (success)". If the pop-up window indicates a failed test, contact your system administrator for troubleshooting.

The image above shows where to find the “Test connection” button in the configuration profile overview and a success message.

Configure Payment Modes

To configure the list of payment modes, go to Price settings > Payment Modes

This list shows all available payment methods in your system. (De)activate any payment method by setting the "Is Active" flag accordingly. Once a new payment method has been added to your Worldline account, you may have to add in manually. To do so, click on the "+" button on top of the list. 

Configure recurring payments

To configure recurring payment, go to Worldline > Worldline Recurring Token

This list shows all available tokens for recurring payments in your system. Click in the respective line in the table to get a comprehensive overview about the individual token and possible actions: 

Property Description
Token Unique identifier of the token on our platform. Returned by our platform when creating the token with the first order.
Alias Masked card number linked to this token. 
Cardholder name Name of the cardholder linked to this token.
Expiry date Expiry date of the card linked to this token. 
Subscription ID Unique identifier of the replenishment order and of the cronjob generating all subsequent orders.
Status

The token's status. Possible values: 

  • Active: Can be used for recurring payments.
  • Blocked: The plugin blocks the usage of the token. 
  • Revoked: Token has been deleted on our platform and cannot be used anymore.
Customer

Unique identifier of your customer who placed the initial order when creating the token. Refer to the Administration tab for more information. 

Store

Unique identifier of the store ID managing the replenishment. Refer to the Administration tab for more information. 

 

The screenshot shows where to find Payment Modes/Worldline Recurring Token in the SAP back office.

Manage SEPA mandates

To manage mandates for SEPA Direct Debits payments, go to Worldline > Worldline Mandates > ORGANIZATION or ADDRESS tab. 

This list shows all available mandates in your system. Click in the respective line in the table to get a comprehensive overview about the individual mandate and possible actions: 

Property Description
Iban Bank acount number (IBAN) linked to this mandate.
CompanyName Company name of the customer linked to this mandate.
EmailAddress E-mail address of the customer linked to this mandate. 
Country Billing data of the customer linked to this mandate.
City
Street
House Number
Zip code
Title
First Name
Last Name
Store Unique identifier of the store ID managing the order linked to this mandate.
Unique Mandate Reference Unique identifier of the mandate on our platform. Returned by our platform when creating the mandate with the first order.
Customer Unique identifier of the customer linked to this mandate.
Status

The Mandate's status. Possible values:

  • Active: Can be used for subsequent orders.
  • Blocked: The plugin blocks the usage of the mandate. 
  • Revoked: Your customer has irreversibly revoked the mandate. 

You can manually activate/block mandates using the respective "Block"/"UnBlock" buttons. Mind that clicking the "Revoke" button is irreversible. 

Recurrence type

The mandate's validity. Possible values:

  • Recurring: The mandate is valid for the for an indefinite amount of subsequent transactions.
  • Unique: The mandate is valid for one payment.
Customer reference

Unique reference for your customer pointing to the order ID or subscription ID when creating the mandate.

The screenshot shows where to find Worldline > Worldline Mandates in the SAP back office.

Manage payments

We have designed the plugin to follow-up on your orders automatically and autonomously, freeing you from the administration involved. Learn here how to use our plugin effectively which could help your business to thrive!

Perform maintenance operations

Captures, refunds and cancellations of authorisations are standard processes (also known as maintenance operations) in your everyday business logic. Learn here how to perform these operations in the SAP Backoffice.

Perform test transactions

Use our platform's test environment to make sure your plugin works as intended. We offer test data sets on our dedicated Test cases page. Target our test environment as described in the "Configure Plugin" section.

Make sure to switch to the LIVE environment as soon as you have finalised your tests.

Was this page helpful?

Do you have any comments?

Thank you for your response.