marcopolo Online payment
Sign up

Salesforce Commerce Cloud

    Introduction

    Our Salesforce 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:

    • Manages multiple stores.
    • Accepts payment operations (Refunds, authorisations, captures etc.) directly from your Salesforce Commerce Cloud Business Manager.

    Keep an eye on our Release Notes to stay informed about updates and new features (i.e. payment methods, features, integration methods) 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 Salesforce Commerce Cloud / Demandware.

    Account Creation

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

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

    Installation

    1. Install plugin
    2. Configuration
    3. Manage payments

    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
    ANZ Worldline Payment Solutions credentials
    Salesforce Commerce Cloud

    Compatibility with Salesforce Commerce Cloud version Storefront Reference Architecture (SFRA).

    • v5
    • v6
    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.

    Once done, follow these steps:

    1. Install cartridge
      You can use the cartridge with Storefront Reference Architecture (SFRA). Install the cartridge to your project root directory at the same level as storefront-reference-architecture. Have a look at this folder structure example: 
      
my-project/
|-- link_worldline_direct/
|  |-- cartridges/
|  |  |-- bm_worldline_direct/
|  |  |-- int_worldline_direct/
|  |-- documentation/
|  |-- metadata/
|-- storefront-reference-architecture
|  |-- cartridges/
|  |  |-- app_storefront_base/
|  |  |-- modules/

    If you have renamed the storefront-reference-architecture folder, make sure to update the base path in package.json.

    1. Install Node modules
      From the cartridge’s root directory, install Node modules using your command line: 
      
npm install

    2. Build code
      From the cartridge’s root directory, compile the client-side assets using your command line: 
      
npm run build
    3. Upload code
      Upload int_worldline_direct and bm_worldline_direct using Commerce Cloud UX Studio or
      sgmf-scripts command line utils.

    4. Import metadata
      To add new configuration items, import the predefined metadata by following these steps:
      • Open the /metadata/site_import/sites/ folder.
      • Rename the yourSiteId folder to the ID of your site in the Business Manager.
      • Zip the site_import folder.
      • In the Business Manager, go to Administration > Site Development > Site Import & Export and import the zipped file.


      After the import, attributes named WorldlineDirect[attributeName] are added to Administration > Site Development. >.

      System Object Types > Site Preferences > Attribute Definitions
      System Object Types > Order > Attribute Definitions
      System Object Types > OrderPaymentInstrument > Attribute Definitions
      System Object Types > CustomerPaymentInstrument > Attribute Definitions
      Custom Object Types

      The service worldline.https.direct.yourSiteId is added to Administration > Operations > Services.

    Configuration

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

    You need to enforce HTTPS in the Salesforce Commerce Cloud to be compatible with the Chrome v80 policy.

    Login to the Business Manager. Set the following values in the menus and confirm by clicking "Apply" or "Save":

    Set Cartridge paths

    To embed an external module and link it with the Business manager, follow these steps:

      • Go to Administration > Sites > Manage Sites > [yourSite] > Settings. Enter the following in "Cartridges":

        int_worldline_direct:app_storefront_base
    The image above shows where to add the value in the Settings menu
      • Go to Administration > Sites > Manage Sites > Manage the Business Manager site > Settings. Enter the following in front of any other existing cartridges:

        bm_worldline_direct:int_worldline_direct:bm_app_storefront_base:bm_custom_plugin
    The image above shows where to add the value in the Settings menu

    Define Business Manager permissions

    Manage the access rights of the module to ensure correct interaction with your Business manager and storefronts:

      • Go to Administration > Organization > Roles & Permissions. Click on the role you want to update in the table. Go to Business Manager Modules.
      • In the "Select context" pop-up, select all storefront sites that will use Worldline-Direct Payments Cartridge.

    Configure credentials for Test/Live environment

    To target our test/live environment and make sure that your requests are legitimate, you need to configure URL endpoints and an API key/secret pair linked to a specific PSPID.

    • Go to Administration > Operations > Services. Open the “Credentials” tab.
    • Click on the worldline.https.direct.yourSiteId.TEST in column “Name” in the table to configure either test/live. Perform the action for both environments.
    The image above shows where to select the name representing the test/live environment
    • Enter the following in the table:
    Property Description/Actions
    Name Replace yourSiteId with the actual ID for your site.
    URL The test or live endpoint on our platform. Copy them from our dedicated guide.
    User Enter the API key of your test or live PSPID. Read our dedicated guide to learn how to generate one.
    Password Enter the API secret of your test or live PSPID. Read our dedicated guide to learn how to generate one.
    • Open the Services Tab. Click on worldline.https.direct.yourSiteId and enter the following in the table:
    Property Description/Actions
    Name Replace yourSiteId with the actual ID for your site.
    Communication Log On test environments, the communication log could be enabled for debugging purposes.
    Credentials Check the updated service credentials are selected.

    Perform the action for both environments.

    • Read our dedicated guides about API endpoints and authentication to get a thorough understanding about the test/live environment and API key/API secret.
    • We strongly recommend configuring a separate name for both our test and live environment. This will allow you to manually switch from one environment to the other easily.
    • Make sure not to mix up credential from test with live and vice versa.

    Set up Merchant ID, Data Locale and Operation code

    Every transaction is channeled via a test/live PSPID on our platform. You also need to define whether our platform processes transactions in authorisation or direct sale mode. If your customers’ native language is different than English, you also need to define the language of the payment pages via the locale.

    • Go to Merchant tools > Site Preferences > Custom Preferences. Click on “WORLDLINE_DIRECT” in column “ID” for setting up your general configuration to connect your store to our platform. Perform the actions as stated in the table:
    The image above shows where to select the ID to be configured
    • Enter the following data on the site:
    Property Description/Actions
    Merchant ID Enter the PSPID on our platform you want to use for transaction processing
    Date Locale Optional – only relevant if your storefront site uses a different locale than English
    You must set the Date pattern in an unused English locale. ie.: en_EN , en_CA

    Used to generate a signature to authenticate requests sent to our platform. One of the headers used to generate this signature is the date, which needs to be in a specific format.

    The locale also defines the language of the payment pages.

    To set up the locale, follow these steps:

    • Go to Administration > Global Preferences > Locales. Click on a locale from the list (column “Locale ID”).
    • Go to tab Regional settings. Enter “EEE, dd MMM yyyy HH:mm:ss z” in Date Settings > Long Date Pattern.
    • Go back to Merchant tools > Site Preferences > Custom Preferences > WORLDLINE_DIRECT. Enter the locale from the list (column “Locale ID”) you have just configured.

    Make sure to use only locales that are available on our platform. Find a full overview for both Hosted Checkout Page and Hosted Tokenization Page here.
    Operation code

    Define whether to process the transactions as authorisation mode or as direct sale. Select one of the following options:

    • Authorisation (FINAL_AUTHORISATION): 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 (SALE): the amount has been ordered to be paid out in one go. Successful transactions will have StatusCode=9.

    If you authorise payments only, make sure that you capture them later. Only then will the transaction reach StatusCode=9, for which you receive funds.

    Use either a

    • Automatic Capture Job: You can set the capture delay of X days in the given field. At the end of this duration, a cron job will capture the transaction automatically.
    • Custom capture procedure: You can manually capture funds fully / partially by opening an individual order once you have delivered the goods/services.
    Checkout Type

    You can process card payments either via Hosted Tokenization Page or Hosted Checkout Page, whereas the alternative payment methods are available only via Hosted Checkout Page.
    3DS settings
    • Set Enforce Strong Customer Authentication to Yes or No.
    • 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.
    Apply Surcharge

    Make sure that the Surcharging is activated in your ANZ Worldline Payment Solutions account.
    Set Line Item Prices to the API

    Set to YES to make sure payment methods that require line item prices work. 

    Configure payment methods and integration modes

    We categorise payment methods in two different clusters:

    • Card payments
    • Alternative payment methods

    You can process card payments either via Hosted Tokenization Page or Hosted Checkout Page, whereas the alternative payment methods are available only via Hosted Checkout Page.

    Follow these steps to make your choice:

    • Go to Merchant tools > Ordering > Payment methods. Click on either “WORLDLINE_DIRECT_CARD”/”WORLDLINE_DIRECT_REDIRECT” in column “ID”. Make sure to select YES for enabled. Perform the actions as stated in the table:
    ID value Description/Actions
    WORLDLINE_DIRECT_CARD Covers all card-based payment methods

    You can offer these to your customers in two ways:
    • 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.

      Select “(1) Hosted Tokenization Page” to use this option.

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

      Select ”(2) Hosted Checkout Page” to use this option.

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

    Covers all alternative payment methods (digital wallets, mobile payment methods, gift cards etc.).

    Upon selection of the brand, the plugin redirects your customers to our Hosted Checkout Page or to the third-party provider for entering the payment credentials.

    Only option ”(2) Hosted Checkout Page” is available for these payment methods.
    • Go to Merchant tools > Site Preferences > Custom preferences. Click on either of them in column “ID” to configure and customise them.
    The image above shows where to select the “WORLDLINE_DIRECT_CREDIT”/ ”WORLDLINE_DIRECT_REDIRECT” to be configured
    ID value Description/Actions
    WORLDLINE_DIRECT_HTP

    Settings for the Hosted Tokenization Page

    • Checkout type: select either
      • Hosted Checkout Page (1): Instead of using Hosted Tokenization Page for card payments, all payment methods are offered via Hosted Checkout Page.
      • Hosted Tokenization Page (2): All Hosted Tokenization Page payment methods available are offered via this integration.
    • Hosted Tokenization JS: Enter the valid tokenisation URL as an iframe on your checkout page. Find it in our documentation.
    • Hosted Tokenization Template: 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 the Hosted Tokenization Page guide.

    If you select Hosted Checkout Page for integration method, upload the payment page template in Worldline_Direct_Redirect.
    WORLDLINE_DIRECT_HCP

    Settings for the Hosted Checkout Page

    • Hosted Checkout Template: Enter the file name of your template to adapt our payment page to the look and feel of your shop. To learn how to create templates, see our dedicated chapter in the Hosted Checkout Page guide.

    Configure webhooks

    The plugin uses webhooks to get the current status of your transactions from our platform. This way your store database is always up to date.

    • Configure a WebhooksKey, WebhooksKeySecret and Endpoint URLs in your PSPID as described in our dedicated guide. Make sure to use the following formula for your endpoint URLs:
      https://{domain}/on/demandware.store/Sites-{yourSiteId}-Site/{locale}/WorldlineDirect-Webhooks
    • Go to Merchant tools > Site Preferences > Custom preferences. Click on “WORLDLINE_DIRECT_WEBHOOKS” in column “ID”. Perform the actions as stated in the table:
    The image above shows where to select the “WORLDLINE_DIRECT_WEBHOOKS” to be configured
    ID value Description/Actions
    Webhooks Key ID

    Enter the webhooks Key ID of your test or live PSPID from the previous step.
    Webhooks Key Secret Enter the Webhooks Key Secret of your test or live PSPID from the previous step.
    • Go to Administration > Operations > Jobs. Click on “WorldlineProcessWebhooks” in the list. Go to Job Step to set the scope to your site. Configure the schedule for the job based on your needs.

    Depending on your business volume for near real-time transaction processing, we recommend setting the job schedule between 1 and 5 minutes. The default value for job schedules is 5 minutes.

    Find a thorough overview on possible webhook events in our dedicated documentation.

    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 Merchant Tools > Ordering > Worldline-Direct Transactions. Click on the “Test API connection” button. Check that the appearing dialogue box states “Connection to the Worldline-Direct API succeeded”.
    The image above shows where to find the “Test API connection” button in the Business Manager

    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!

    Follow-up on orders Check payment status / Process unconfirmed orders

    To make sure

    • your platform registers successful payments (StatusCode=5 or 9 and Status=”PAYMENT_CREATED”) as such and not as unfinished (because of a failed redirection of your customers to the Salesforce Commerce Cloud website.
    • authorised transactions are finalised by a capture (If you choose Operation Code: Authorisation during the initial order).

    the plugin implements the “Check payment status job”. Follow these steps to make them work:

    • Modify property cancelUnconfirmedOrderAfterHours to the desired amount of hours after which the plugin cancels an order in a pending status.
    • Check out how to capture authorisations automatically or manually.

    Capture authorisation automatically

    If you choose to authorise transactions only during the initial order, our plugin will capture them for you at a later point. You can define the intervals and the timing for the captures based on your business requirements.

    Go to Administration > Jobs > WorldlineCaptureAuthorizedPayments > Schedule and History. Perform the actions as stated in the table for the respective capture mode:

    Capture mode Description/Actions
    Capture authorisations several times a day
      • Check the “Enable” checkbox
      • Set “Trigger” to “Recurring interval”
      • Set “Interval” to “Hours” and “Amount” to the desired time span (in hours) that should pass between the captures
      • Define the time of the initial capture in “From”. Counting from this time, captures are run every X hour you defined in “Amount”
      • Set “WorldlineDirectCaptureProcedureDelay” to define which authorisations from X days ago should be captured
    Capture payments at the end of the day
      • Check the “Enable” checkbox
      • Set “Trigger” to “Recurring interval”
      • Set “Interval” to “Days” and “Amount” to “1”
      • Define the time of the capture in “From”
      • Set “WorldlineDirectCaptureProcedureDelay” to “0” to ensure all pending authorisations are captured at the end of the same day without any delay

    The timing of the captures depends on the time zone you have configured in the Business Manager. Check this on the bottom of your browser.

    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 Business manager:

    Go to Merchant Tools > Ordering > Worldline-Direct Transactions. Look up the transaction in question and click on “Details” in column “Category”. The dialogue box shows the possible actions you can perform on a transaction. Perform the action as stated in the table to perform the respective maintenance operations.

    The image above shows how to reach the menu to perform maintenance operations The image above shows how to reach the menu to perform maintenance operations

    This is an example of the user interface. The available currencies depend on your configuration, region and transaction context.

    Maintenance operations Description/Actions
    Capture

    Capture authorised transactions (StatusCode=5 / Status=PENDING_CAPTURE) to effectively receive the funds for the order:

      • Click on the “Captures” tab. The table shows all captures so far.
      • In “Add a new capture”, add the (partial or full) amount in “Amount” and click on the “Capture” button to confirm. If you have not captured the full amount yet, you can perform multiple follow-up captures until you have reached the full amount.

    If you want our plugin to capture transactions automatically, follow these instructions.
    Maintenance operations Description/Actions
    Cancellations

    Cancel authorised transactions (StatusCode=5 / Status=PENDING_CAPTURE)

      • Click on the “Refunds” tab. The table shows all refunds so far.

    Maintenance operations Description/Actions
    Refunds

    Reimburse your customers for captured transactions (StatusCode=9 / Status=COMPLETED)

      • Click on the “Refunds” tab. The table shows all refunds so far.
      • In “Add a new refund”, add the (partial or full) amount in “Amount” and click on the “Refund” button to confirm. If you have not refunded the full amount yet, you can perform multiple follow-up refunds until you have reached the full amount.

    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.
    Help & Info
    API Info
    Developer Tools
    ANZ Worldline Payment Solutions means Worldline Australia Pty Ltd ACN 645 073 034 ("Worldline"), a provider of merchant solutions. Worldline is not an authorised deposit taking institution (ADI) and entry into any agreement with Worldline is neither a deposit nor liability of Australia and New Zealand Banking Group Limited ACN 005 357 522 ("ANZ") or any of its related bodies corporate (together "ANZ Group"). Neither ANZ nor any other member of the ANZ Group stands behind or guarantees Worldline.