Introduction

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

References

• Public Release Note - Concardis Service Connector 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 (valid to 7.10) 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

Setting Up the Assembly

To add the Concardis 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 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:

   Step 1

   ...
    
   cartridges {
           def storefrontCartridges = [
               'app_sf_responsive',
               'app_sf_responsive_cm',
               'app_sf_responsive_b2c',
               'app_sf_responsive_smb',
               'as_responsive',
               'app_sf_responsive_b2b',
               'app_sf_responsive_costcenter',
               'as_responsive_b2b',
   // these are the two cartridges, which we delivered in source code and you have to add these files to your responsive source project
               'as_responsive_concardis',
               'app_sf_responsive_concardis'
              ]
           include(*(storefrontCartridges.collect { project(":$it") }), in:[development, test, production])
     
   ...
    
           def concardisPaymentProvider = [
               'ac_payment_concardis', 
           ]
           include (*(concardisPaymentProvider.collect {"com.intershop.services.payment_concardis:$it"}), in: [development, test, production])    
     
           order = listFromAssembly(baseAssembly) + concardisPaymentProvider 
       }
   ...
   assemblyBuild {
       database {
           inherit(<yourAssembly>)
           initCartridges = []
       }
   }
   ...
   

2. Adapt the app_sf_responsive_concardis/build.gradle file in the following way:
   

   Step 2

   apply plugin: 'static-cartridge'
    
   intershop
   {
          displayName = 'Adapter - Payment Concardis - Business Extensions'
   }
    
   dependencies
   {
   //   compile project(':ac_payment_concardis') --> will be replaced by
        compile group: 'com.intershop.services.payment_concardis', name: 'ac_payment_concardis'
   
      compile group: 'com.intershop', name: 'api_service'
   ...
   }
   
   

3. Adjust the file as_responsive_concardis/build.gradle in a similar way:
   

   Step 3

   ...
   dependencies {
   //  compile project(':ac_payment_concardis') --> will be replaced by 
       compile group: 'com.intershop.services.payment_concardis', name: 'ac_payment_concardis'
       compile project(':app_sf_responsive_concardis')
   }
   ...

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

   Step 4

   com.intershop.services.payment_concardis:ac_payment_concardis = 2.0.0

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

For details about managing assembly artifacts see:

• Concept - Gradle Assembly Tools
• Reference - Gradle Assembly Tools
• Cookbook - Gradle Assembly Tools

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 Concardis Service Connector.

The Concardis Service Connector requires the following settings:

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

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

Additionally, the countries where a payment method is available can be defined in <IS_SHARE>/system/cartridges/ac_payment_concardis/release/config/countriesConfigurations.properties. The values can be defined as whitelist or blacklist.

The values are dependent on the countries that are supported for these payment methods by Concardis.

Deploying the Assembly

After creating and appropriately configuring the assembly, you must deploy it to the intended target environment.

For details about deploying an assembly, see Recipe: Run the Deployment (Initial Installation / Upgrade / Downgrade).

This section outlines the required post-deployment configuration steps, including

• Setup Concardis Service Connector | Applying UI-Based Configuration
• Setup Concardis Service Connector | Localization

Configuration

Applying UI-Based Configuration

The Concardis 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.

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.

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 checkbox Active.

10. Select the checkbox Available.

11. Click Next.

12. Enter all Concardis general settings.
    Card Number Style ID and CVC Style ID are mandatory when using the PWA (Progressive Web App Storefront).

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 Concardis-specific settings for configuring the payment service.

Customize CSS for Credit Card and CVC Input Field

The CSS file has to be customized to style the Credit Card and CVC input field, which will be displayed to the customer in the checkout payment step. Therefore, two custom styles must be created in the Payment Merchant Center.

This can be done in the Payment Merchant Center:

1. Go to Settings | Custom Styles.
   
2. Click Create Custom Style and choose either Write CSS or Upload CSS file.
   
3. Add your customized CSS for the credit card input by using the ID payengine-credit-card-input.
   
4. Click Save.
5. Repeat steps 1-4 for the CVC input field by using the ID payengine-verification-input. 

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.

Localization

The Concardis 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_concardis/release/localizations.

For details about localization see Concept - Localization.

Adjusting Firewall Settings

Adjust your firewall settings to allow bidirectional HTTPS traffic between Intershop 7 and Concardis. Make sure that the <host>:<port>/INTERSHOP/rest/WFS/inSPIRED-inTRONICS-Site/-/concardis/notifications/*  is accessible from the Concardis IP addresses only. Please contact your Concardis account manager to ask for more details about the valid IP addresses.

Customization

Adding a Custom Applicability Check

It is possible to add a custom applicability check in order to display the payment method only if additional conditions are met.

To provide a custom check in one of the payment methods (e.g., CreditCard), you need to create a new class:

public class CustomCreditCardApplicabilityCheckImpl implements ApplicabilityCheck
{
    @Override
    Result<ApplicabilityResult> getApplicability(Payable payable, String serviceName, BaseConfiguration baseConfiguration);
    {
		Result<ApplicabilityResult> result = new Result<>(new ApplicabilityResult());
        result.setState(ApplicabilityResult.APPLICABLE);

		boolean customConditionMet = true; // do your additional checks, e.g. based on data in `Payable`
		if (! customConditionMet )
		{
			result.setState(ApplicabilityResult.NOT_APPLICABLE);
		}
		return result;
    }
}

The current Payable is handed in, so you can compute the applicability of the payment method based on the data.

Then you need to bind your class in a custom Guice Module. In this case it has to be something like this:

Multibinder<ApplicabilityCheck> applicabilityBinder = Multibinder.newSetBinder(binder(), 
                        ApplicabilityCheck.class, named("Concardis_CreditCard_ApplicabilityChecks"));
applicabilityBinder.addBinding().to(CustomCreditCardApplicabilityCheckImpl.class).in(Singleton.class);