Guide - Setup Cybersource Service Connector

1 Introduction

This guide outlines the basic setup and configuration steps for the Cybersource Service Connector. 

1.1 References

1.2 Preconditions

The package is available via Intershop's Public Repository (Artifactory). Furthermore, the following preconditions are required:

  • A set up and configured continuous integration (CI) environment
    See Cookbook - Setup CI Infrastructure for details.
    See Concept - Continuous Delivery Tools for basic information about continuous integration.
  • A running Intershop Commerce Management 7.10 installation that matches the system requirements
  • Knowledge of how to add the delivered artifacts to the continuous integration environment
  • Knowledge of how to deploy to a test or production environment

2 Setting Up the Assembly

To add the Cybersource Service Connector into your Intershop 7 system, you can either incorporate the cartridge into an already existing assembly or create a new assembly inheriting from an Intershop-7-based assembly. For details about creating a new assembly, see Cookbook - Gradle Assembly Tools | Recipe: Create a New Assembly Inheriting From an Existing Assembly. If you want to incorporate the cartridge into an already existing assembly, perform the following steps:


  1. Add the following to the  build.gradle  file of the assembly:

    ...
      
    cartridges {

    ...
      
             def cybersourcePaymentProvider = [
                 'ac_payment_cybersource' ,
             ]
             include (*(cybersourcePaymentProvider.collect { "com.intershop.services.payment_cybersource:$it" }), in: [development, test, production])   
       
             order = listFromAssembly(baseAssembly) + cybersourcePaymentProvider
         }
    ...
    assemblyBuild {
         database {
             inherit(<yourAssembly>)
             initCartridges = []
         }
    }
    ...

  2. Insert the following lines into the file:  intershopBuild.version

    com.intershop.services.payment_cybersource:ac_payment_cybersource = 1.0.0

    For details about adding components to an assembly, see  Recipe: Add Cartridges to an Assembly.


For details about managing assembly artifacts see:

3 Defining File-Based Configuration

Before deploying the new assembly to a test or production environment, you may have to adjust some file-based configurations required by the Cybersource Service Connector.

The Cybersource Service Connector requires the following settings:

PropertyDescriptionValue
intershop.payment.CyberSource_CreditCard.currenciesDefines which currencies are configurable for Cybersource Credit Card. (Default: USD, EUR, GBP, AUD)Comma-separated list of currency codes, e.g. USD, EUR, GBP, AUD
intershop.payment.cybersource.apiBaseUrl.sandbox

Defines the base URL used for requests to the Cybersource sandbox. Default:  https://apitest.cybersource.com

Leave at default value unless URL of API endpoint on Cybersource changes.

URL to the sandbox (provided by Cybersource)
intershop.payment.cybersource.apiBaseUrl.production

Defines the base URL used for requests to the Cybersource production environment. Default:  https://api.cybersource.com

Leave at default value unless URL of API endpoint on Cybersource changes.

URL to the production system (provided by Cybersource)

According to  Recipe: Change Deployed File Content With Filters  this setting has to be overridden within <IS_SHARE>/system/config/cartridges/ac_payment_cybersource.properties.

For details about adding new configuration files, see  Recipe: Deploy Custom Files.

4 Deploying the Assembly

After having created and appropriately having configured the assembly, you must deploy it to the intended target environment.

For details about deploying an assembly, see Cookbook - Deployment Tools ICM 7.10 | Recipe: Run the Deployment (Initial Installation / Upgrade / Downgrade).

Note

The Cybersource Service Connector requires additional post-deployment configuration steps. For details, refer to Setup Cybersource Service Connector | Configuration.


5 Configuration

5.1 Prepare Shared Key

In order to configure the payment service, a shared key needs to be created in the Cybersource Enterprise Business Center (EBC) back office.

  1. Log in into Cybersource EBC.
  2. Go to Payment Configuration | Key Management.
  3. Click GENERATE KEY.



  4. Select REST - Shared Secret.



  5. Click Generate key at the bottom of the page.
  6. Copy the newly generated public key (optional: download the key file). The key is required for the configuration of the managed service.

    Note

    The generated key is only visible in this step and this screen will not be reachable again later.

  7. Go back to Key Management and click the link to the newly generated key.

    Note

    If the link in question is not visible in the list, change the filter to API Keys.
  8. Copy the corresponding key ID (i.e., the value that is displayed as Key Detail).

Both the key and key ID are required for the configuration of the managed service.

5.2 Applying UI-Based Configuration

The Cybersource Service Connector requires some post-deployment configurations in the Organization Management application and in the Commerce Management application.

For details about enabling a payment service see Cookbook - Payment | Recipe: Enable a Payment Service.

5.2.1 Configure the Application External Base URL

External Base URL is required for generating IFrames for input fields (credit card number and CV) for credit card payment method. In case of a wrong value for this configuration, the input fields will appear as blocked and the user will not be able to enter the values in these fields.

  1. Log in to Organization Management.
  2. Navigate to Sales Organizations.
  3. Select the name of the Sales Channel.
  4. Navigate to Applications
  5. Select Progressive Web App application.
  6. Set the configuration External Base URL as https://domain-name:port (domain-name is complete URL for your PWA shopping website and port is port number on which the website is running). The protocol must be Hypertext Transfer Protocol Secure (https). For development purpose the value can be set to  http://localhost:port.   Please refer to screenshot below for example.

5.2.2 Assign Payment Services to a Sales Organization

  1. Log in to Organization Management.
  2. Navigate to Sales Organizations.
  3. Select the name of the organization.
  4. Go to Services |  Payment Services.

  5. Select the checkboxes of the new payment methods you intend to enable for the current sales organization.
  6. Click Enable.

5.2.3 Create a Managed Payment Service

  1. Log in to Commerce Management.
  2. Select the Organization/Channel.
  3. Go to  Services.

  4. Click  New.
  5. Select the new payment service.

  6. Click  Next .

  7. Enter a Payment Service Name.

  8. Enter "Service ID".

  9. Select the check box  Active.

  10. Select the checkbox  Available.

  11. Click  Next.

  12. Enter all Cybersource general settings.
    Use the copied key and key ID obtained from the key generation for the fields here:

    • Merchant Key ID = key ID

    • Merchant Shared Secret = public key

  13. Enter all logging settings.

  14. Enter all monitoring settings.

  15. Click  Next.

  16. Select the  Sharing Rule.
    (When setting up in the organization area, the service  must necessarily be shared to the channel.)

  17. Click  Finish.
    The table below lists Cybersource-specific settings for configuring the payment service.

NamePayment MethodsDescription
MerchantIDAllThe merchant account's merchant ID as provided by Cybersource
RunEnvironmentAllDefines whether "Sandbox" for test and development is used or "Production" for production.
MerchantSecretKeyAllThe merchant account's Shared Secret Key as provided by Cybersource
MerchantKeyIdAllThe merchant account's API Key as provided by Cybersource
CaptureAll

Capture "Auto" will automatically do authorization and capture in one step. Capture "Manual" separates authorization from capture process, so capture has to be done manually at the order when the items are shipped.

SubmitOrderDetailsAllThis enables or disables the ability to send all product line items information to Cybersource.
SubmitAddressDetailsAllThis enables or disables the ability to send shipping address information to Cybersource.

5.2.4 Configure the Payment Methods

To enable the payment method for the channel,
log into Commerce Management and perform the following steps:

  1. Select the context selection box.
  2. Select the sales channel.
  3. Click  Orders.
  4. Click  Payment Methods.
  5. Click New.
  6. Enter  Payment Method ID.
  7. Select the Configuration Type.
    The type was created in the section Create a Managed Payment Service.
  8. Click  Apply.
  9. Click  Applications.
  10. Select the checkboxes of all applications for which the payment method should be enabled.
  11. Click  Enable.
  12. Click  Payment Costs.
  13. Define taxation class, currency, minimum order value, amount and/or threshold for the payment method if desired and click  Add.
  14. Click  Apply.
  15. Click  Customer Segments.
  16. Enable the target customer segments.
  17. Click  Apply.
  18. Click  Preferences.
  19. Select the currency-dependent availability and the payment currency.
  20. Click  Apply.

5.3 Localization

The Cybersource Service Connector provides English, French and German localization files for payment-specific input field labels. 

You can find the existing localization files here:  <IS.INSTANCE.SHARE>/system/cartridges/ac_payment_cybersource/release/localizations.

For details about localization see  Concept - Localization.














Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets