Salesforce Commerce Cloud

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

Once done, follow these steps:

1. Install cartridge
   Install the cartridge to your project root directory at the same level as storefront-reference-architecture. Here is an example of the folder structure:

   
   my-project/
   |-- link_worldline_gopay/
   |  |-- cartridges/
   |  |  |-- bm_worldline_gopay/
   |  |  |-- int_worldline_gopay/
   |  |-- 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.

2. Install Node modules
   The recommended Node version to use is 12.21.0. From the cartridge’s root directory, install Node modules using your command line:

   npm install

3. Build code
   From the cartridge’s root directory, compile the client-side assets using your command line:

   npm run build

4. Upload code
   Upload int_worldline_gopay and int_worldline_gopay_sfra using Commerce Cloud UX Studio or
   sgmf-scripts command line utils.

5. 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 WorldlineGoPay[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.gopay.yourSiteId is added to Administration > Operations > Services.

   Upgrades from previous versions

   Version v26.3.0 of the plugin introduces a major refactoring and rebranding of the cartridge to . As part of this change, we renamed the cartridge code, metadata attributes, services, payment configuration, and other components that used the 'worldlineDirect' naming convention. They now use the new naming convention.

   worldlineGoPay
   Existing orders and customer payment instruments may still contain data in the previous attributes. The upgrade therefore includes a migration job. The job copies the relevant data from the old attributes to the new 'worldlineGoPay' attributes.

   Follow these steps:

   1. Replace existing cartridges
      • Remove:
        int_wordline_direct
        bm_worldline_direct
        
        
      • Add:
        int_worldline_gopay_sfra
        int_worldline_gopay
        bm_worldline_gopay
        
        Update the cartridge paths for the relevant site(s) and Business Manager configuration wherever required.
        
        
   2. Import metadata
      Import the metadata using the standard import process described in the Installation section.
      The import creates the new configuration, including the required:
      
      • System Object attributes
      • Custom Object Types
      • Services, profiles and credentials
      • Jobs
      • Payment Methods
      • Payment Processors
      • Site Preferences
      • Other cartridge metadata included in the package
        
        
   3. Configure and run the migration job
      Create and configure a new job under Administration > Operations > Jobs. Add a job step using the newly created step: custom.worldlineGoPayRebrandingJob and configure the following parameters:
      migrateOrder – whether to migrate data stored against existing orders.
      migrateCustomerSavedInstruments – whether to migrate existing saved customer
      payment instruments.
      
      Run the migration job after importing the new metadata has been imported. Based on the configured parameters, the migration job will migrate the relevant information for:
      Existing orders
      Existing customer payment instruments
      
      
   4. Remove the old metadata
      The exact metadata present may depend on the previously installed cartridge version. Remove all deprecated configurations associated with Worldline Direct / worldlineDirect.
      a) Administration > Operations > Services
      Delete all deprecated Worldline Direct:
      Services
      Profiles
      Credentials
      
      b) Administration > Operations > Jobs
      Review existing jobs and replace any deprecated Worldline Direct job steps with their corresponding job steps. Ensure that the associated job parameters are also updated where required.
      
      c) Administration > Site Development > Custom Object Types
      Delete the deprecated Worldline Direct Custom Object Types:
      WorldlineDirectPaymentProducts
      WorldlineDirectWebhooks
      
      d) Administration > Site Development > System Object Types
      Remove deprecated worldlineDirect attributes and attribute groups from the relevant System Object Types across:
      CustomerPaymentInstrument
      OrderPaymentInstrument
      Order
      SitePreferences
      
      e) Merchant Tools > Payment Methods
      Delete the deprecated payment methods associated with Worldline Direct:
      WORLDLINE_DIRECT_CARD
      WORLDLINE_DIRECT_REDIRECT
      WORLDLINE_DIRECT_CREDIT_REDIRECT
      WORLDLINE_DIRECT_DIRECTDEBIT
      
      f) Merchant Tools > Payment Processors
      Delete the deprecated payment processors associated with Worldline Direct:
      WORLDLINE_DIRECT_CARD
      WORLDLINE_DIRECT_REDIRECT
      WORLDLINE_DIRECT_CREDIT_REDIRECT
      WORLDLINE_DIRECT_DIRECTDEBIT
      
      
   5. Configure the new cartridge as per the instructions given in the section "Configuration".
      
      
   6. Verify the upgrade by checking that
      a) services are configured and operational.
      b) Existing migrated orders contain the Worldline GoPay data.
      c) Existing customer payment instruments contain the migrated data.
      d) New orders populate the worldlineGoPay attributes rather than the deprecated worldlineDirect attributes.
      e) All supported payment methods can be successfully used during checkout.
      f) Payment authorization, capture, cancellation and refund flows operate as expected, where applicable.
      g) Scheduled jobs are complete successfully.
      h) No runtime dependencies remain on deprecated metadata.

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

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_gopay_sfra:int_worldline_gopay:app_storefront_base

• • Go to Administration > Sites > Manage Sites > Manage the Business Manager site > Settings. Enter the following in front of any other existing cartridges:
    
    

    bm_worldline_gopay:int_worldline_gopay:bm_app_storefront_base:bm_custom_plugin

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-GoPay Payments Cartridge.
  • Find Ordering module in the modules table. Assign Worldline-GoPay Transactions and Worldline-GoPay Subscriptions module permissions for the selected role.

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.gopay.yourSiteId.TEST in column “Name” in the table to configure either test/live. Perform the action for both environments.

• Enter the following in the table:

• Open the Services Tab. Click on worldline.https.gopay.yourSiteId and enter the following in the table:

Perform the action for both environments.

Set up Worldline-GoPay Payments Cartridge

Every transaction is channeled via a test/live PSPID on our platform. 

• Go to Merchant tools > Site Preferences > Custom Preferences. Perform the actions for each of the custom groups as stated in the table below:

WORLDLINE_GOPAY (Shared Config)

Click "Save" in the upper-right corner of the screen.

WORLDLINE_GOPAY_3DS (3-D Secure config)

WORLDLINE_GOPAY_HCP (Hosted Checkout Page Settings)

WORLDLINE_GOPAY_HTP (Hosted Tokenization Page Settings)

WORLDLINE_GOPAY_WEBHOOKS (Webhooks config)

WORLDLINE_GOPAY_MOBILE (Mobile Payments)

Configure payment methods and integration methods

We categorise payment methods into 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 the relevant payment method. Make sure to select YES for enabled. Perform the actions as stated in the table:

You can also fetch, view or hide, customise and sort all available payment methods on your account into the Business Manager. Navigate to Merchant tools > Ordering > Worldline-GoPay Payment Products to see all payment methods available on your account. Refresh the list whenever you activate new payment methods on your account to update it. From this page, you can also hide payment methods if you do not want them to be available on the checkout page.

Additional configurations

1. Mealvouchers

Our plugin supports the Mealvouchers payment method. To make it available, the cartridge adds a custom attribute to the Product object: Mealvouchers product type, with these values:

• FoodAndDrink - Food and beverage items eligible for meal vouchers
• HomeAndGarden - Home and garden items, typically eligible for eco-cheques
• GiftAndFlowers - Gift and flower items potentially eligible for eco-cheques and another voucher type (Cheques Cadeau)

Configure this field per product by including it in your product feed to Salesforce Commerce Cloud or by editing products manually in Business Manager.

2. Subscriptions

The Worldline-GoPay Subscriptions option allows the customer to order a specific set of products from the online store at regular intervals. The intervals can be managed through the plugin.

This feature is available only for registered customers. Please follow the following steps to activate it:

1. Activate Subscriptions through Merchant tools > Site Preferences > Custom Preferences.
2. Go to Administration > Operations > Services and open the Credentials tab to configure the service credentials. Open worldline.gopay.ocapi and edit:
   • URL: add the URL to your site/instance
   • User: enter your API key ID.
   • Password: enter your API key secret.
3.  Click Apply.
4. Configure services by navigating to Services tab.
   • Select worldline.gopay.ocapi credentials.
   • Select a profile for the OCAPI request (create one if none is present) and apply.

Configure webhooks

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

• Configure a WebhooksKeyID, 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}/WorldlineGoPay-Webhooks
• Go to Merchant tools > Site Preferences > Custom preferences > Worldline_GoPay: Webhooks Config and perform the actions as stated in the table:

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

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-GoPay Transactions. Click on the “Test API connection” button. Check that the appearing dialogue box states “Connection to the Worldline GoPay API succeeded”.

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 number 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:

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

Subscriptions

Managing subscription orders has never been this easy! Just like one-off payments, subscription orders can be managed through the business manager.

• Go to Merchant Tools > Ordering > Worldline-GoPay Subscriptions to access the module. This page lists the subscription orders with details.
• Click on the order you want to check the subscription details like period and frequency. You will be able to block/unblock or cancel a subscription through the same page.

Please note that Block Subscription is a temporary status in case of missing stock or payment issues. The status is reversible and can be changed manually once the issues are resolved.

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.

Have a new feature request?

Navigate to Merchant Tools > Ordering > Worldline-GoPay Transactions. You will find the option at the bottom of the page.