Guide - Setup Concardis Service Connector 2

1 Introduction

This guide outlines the basic setup and configuration steps for the Concardis 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 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:

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

The Concardis Service Connector requires the following settings:

PropertyDescriptionValue
intershop.payment.Concardis.apiBaseUrl.sandbox

Defines the base URL used for requests to the Concardis sandbox. Default: https://apitest.payengine.de/v1

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

URL to the sandbox (provided by Concardis)
intershop.payment.Concardis.apiBaseUrl.live

Defines the base URL used for requests to the Concardis live environment. Default: https://api.payengine.de/v1

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

URL to the live system (provided by Concardis)
intershop.payment.Concardis_CreditCard.currenciesDefines which currencies are configurable for Concardis Credit Card. Default: * (all currencies)comma-separated list, e.g., EUR, USD

intershop.payment.Concardis_CreditCard.cvcmaxage

( only in Concardis 1.11.7 and newer )

Defines the maximum time for which CVC remains valid in minutes. The value must be smaller or equal to the valid time on Concardis side (30 minutes). Default: 25 (minutes)Integer, e.g. 25
intershop.payment.Concardis_EPS.currenciesDefines which currencies are configurable for Concardis EPS. Default: EURcomma-separated list, e.g., EUR, USD
intershop.payment.Concardis_Giropay.currenciesDefines which currencies are configurable for Concardis Giropay. Default: EURcomma-separated list, e.g., EUR, USD
intershop.payment.Concardis_iDEAL.currenciesDefines which currencies are configurable for Concardis iDEAL. Default: EURcomma-separated list, e.g., EUR, USD
intershop.payment.Concardis_PayPal.currenciesDefines which currencies are configurable for Concardis PayPal. Default: * (all currencies)comma-separated list, e.g., EUR, USD

intershop.payment.Concardis.DirectDebit.countries

Defines which currencies are configurable for Concardis SEPA Direct Debit. Default: EURcomma-separated list, e.g., EUR, USD
intershop.payment.Concardis_Sofort.currenciesDefines which currencies are configurable for Concardis Sofort. Default: EUR, CHFcomma-separated list, e.g., EUR, USD
intershop.payment.Concardis_Alipay.currenciesDefines which currencies are configurable for Concardis Alipay. Default: AUD,CAD,EUR,GBP,HKD,SGD,USD,NZDcomma-separated list, e.g., EUR, USD
intershop.payment.Concardis_WeChatpay.currenciesDefines which currencies are configurable for Concardis WeChat Pay. Default: EUR, USD, GBPcomma-separated list, e.g., EUR, USD
intershop.payment.Concardis_Bancontact.currenciesDefines which currencies are configurable for Concardis Bancontact. Default: EURcomma-separated list, e.g., EUR, USD


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.

PropertyDescriptionValue
intershop.payment.Concardis.CreditCard.countriesDefines for which country of the invoice address the payment method Credit Card is available. Default: * (all countries)comma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.EPS.countries

Defines for which country of the invoice address the payment method EPS is available. Default: AT

comma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.Giropay.countriesDefines for which country of the invoice address the payment method Giropay is available. Default: DEcomma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.IDeal.countriesDefines for which country of the invoice address the payment method iDEAL is available. Default: NLcomma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.PayPal.countriesDefines for which country of the invoice address the payment method PayPal is available. Default: * (all countries)comma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.DirectDebit.countriesDefines for which country of the invoice address the payment method SEPA Direct Debit is available. Default: DE, CH, ATcomma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.Sofort.countriesDefines for which country of the invoice address the payment method Sofort is available. Default: DE, AT, CH, NL, BE, ES, ITcomma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.Alipay.countries.excludeDefines for which country of the invoice address the payment method Alipay is not available. Default: CNcomma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.WeChatpay.countries.excludeDefines for which country of the invoice address the payment method WeChat Pay is not available. Default: CNcomma-separated list of 2-digit country codes (ISO 3166-1)
intershop.payment.Concardis.Bancontact.countriesDefines for which country of the invoice address the payment method Bancontact is available. Default: BEcomma-separated list of 2-digit country codes (ISO 3166-1)

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

4 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).

Note

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

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

5 Configuration

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

5.1.1 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.1.2 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.

NamePayment MethodsDescription
Merchant IDAllThe merchant account's merchant ID as provided by Concardis
API KeyAllThe merchant account's API Key as provided by Concardis
System health status expiration time

All

Insert the time interval in seconds which checks if the Payengine service is available. If the service is offline, the payment methods are hidden at the payment page in the checkout.
Card Number Style IDCredit CardIn the Concardis Merchant Center the Credit Card input field can be styled with CSS class. Enter the Style ID which was generated in the Merchant Center here.
CVC Style IDCredit CardIn the Concardis Merchant Center the CVC input field can be styled with CSS class. Enter the Style ID which was generated in the Merchant Center here.
CaptureAllCapture "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.
EnvironmentAllDefines whether "Sandbox" for test and development is used or "Live" for production.
Submit Order DetailsAllThis enables or disables the ability to send all product line item information to Concardis.
Submit Address DetailsAll

This enables or disables the transfer of the address to Concardis. Choose "No Address Submission" for no transmission or "Address Field Mapping" to provide custom mapping. 

Please leave this setting on "No Address Submission" in case the address is stored as single attribute on ICM side.

Street MappingAllOnly available if the option "Address Field Mapping" was set for the option Submit Address Details. Maps an address line to the field "street" on Concardis side. 
House Number MappingAllOnly available if the option "Address Field Mapping" was set for the option Submit Address Details. Maps an address line to the field "house number" on Concardis side. 

5.1.3 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

5.1.4 Configure the Payment Methods

Note

Configuring payment methods in a sales channel requires the access privilege Payment Manager for this channel.

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

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

6 Customization

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

CustomCreditCardApplicabilityCheckImpl
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);

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