Public Release Note - Concardis Service Connector 1

1 Introduction

Welcome to the Intershop Concardis Service Connector. The service connector adds Concardis payment methods to your Intershop installation.

This document provides important product information, including version information and dependencies. It also outlines the basic setup and configuration steps.

1.1 References

1.2 Version Information and Dependencies

This delivery and the accompanying documentation are valid for the following combinations of software versions:

IntershopSupported Application TypesPWA*Concardis Service Connector
7.10.15.3intershop.SMB, intershop.B2C0.17.0+

1.1.5

7.10.16.6intershop.SMB, intershop.B2C0.17.0+1.3.0+
7.10.16.6+intershop.SMB, intershop.B2C0.20.0+1.7.0+
7.10.16.6+intershop.SMB, intershop.B2C0.20.0+1.9.0+
7.10.17.0+intershop.SMB, intershop.B2C, intershop.REST**0.20.0 - 0.23.01.10.8+

7.10.26.2-LTS -

7.10.30.x (Tomcat 7)

intershop.SMB, intershop.B2C, intershop.REST0.26.0 - 0.31.01.11.7+

* Please see PWA releases documentation for details.

** Feature of ICM 7.10.21.0

Concardis Connector version 2.0.0 (see Public Release Note - Concardis Service Connector 2) features the same functionality as Concardis Connector 1.11.7 to facilitate migration from ICM 7.10.30- to 7.10.31+.

The next table provides information about the cartridges included in the package. Not all of these cartridges are required.

CartridgeDescriptionRequired
ac_payment_concardisIncludes all base functionality and business logic which is used.(tick)
as_responsive_concardis

Enables the Concardis payment connector for the following application types:

  • intershop.B2CResponsive
  • intershop.SMBResponsive

The cartridge is optional, can be downloaded separately from Intershop Product Calendar and may be included if the project uses the responsive starter store. Unzip the file to your multi-project folder next to your responsive source files. This step can be skipped if the custom project does not support these application types or Concardis is not required in these application types.

(error)
app_sf_responsive_concardis

Includes some additional functionality which is relevant for the responsive storefront reference application only, e.g., the integration of the hosted payment pages of the credit card.

The cartridge is optional, can be downloaded separately from Intershop Product Calendar and may be included in case the project is based on the responsive storefront reference application. Unzip the file to your multi-project folder next to your responsive source files. The referenced cartridge app_sf_responsive may be renamed in the project and has to be referenced in the build.gradle file with the customized naming again.

(error)

The Concardis Service Connector is based on the new Payment API introduced in IS 7.6.

The sources for as_responsive_concardis and app_sf_responsive_concardis can be downloaded here (use your repository login and password for authorization): https://repository.intershop.de//releases/com.intershop.public.source/s_payment_concardis/1.11.7/zips/s_payment_concardis-zip-src-1.11.7.zip

1.3 Supported Application Types

The Concardis Service Connector can be used for the following application types:

Application TypeApplication Type IDDescription
B2C WebShopintershop.B2CResponsiveBusiness to Consumer Channel
SMB WebShopintershop.SMBResponsiveBusiness to Business Channel
Progressive Web Appintershop.RESTBusiness to Customer and Business Channel via REST API
(only available with ICM 7.10.21 and later)

Documentation for Concardis error messages and possible sources of the errors is available here:

https://docs.payengine.de/buildyourown/restdoc/errors

Documentation for the REST API can be found here:

https://docs.payengine.de/buildyourown/restdoc/providercodes

2 Setup

For information on setup, customization and configuration, please refer to Guide - Setup Concardis Service Connector.

3 Feature Overview

3.1 Payment Methods

The Concardis Service Connector adds the following payment methods to your Intershop 7 system:


Payment Method TypePayment MethodAuto CaptureManual Capture*Cancel*Reduce*Refund
Credit Card

Credit Card Payment supported by Concardis e.g.:

  • Visa
  • Mastercard
  • American Express
  • JCB
  • Diners Club

Includes 3DS 2.0 support.

(tick)(tick)(tick)(error)(tick)
Online PaymentAlipay(tick)(error)(error)(error)(tick)

Bancontact(tick)(error)(error)(error)(tick)

EPS(tick)(error)(error)(error)(error)

Giropay(tick)(error)(error)(error)(error)

iDEAL(tick)(error)(error)(error)(tick)

PayPal(tick)(tick)(tick)(tick)(tick)

SEPA Direct Debit(tick)(tick)(tick)(tick)(error)

Sofort(tick)(error)(error)(error)(error)

WeChat Pay(tick)(error)(error)(error)(tick)

* only available if the corresponding payment method's Capture Mode is set to manual. Concardis reserves the authorized amount for a standard duration of 5 days. Afterwards a manual capture fails (error code 21).
The merchant can negotiate a different duration time with Concardis.

3.2 Payment Management Options

The following table lists all options that are available for payment transactions.

OperationDescription
CaptureRequest for settling the payment. This action is only available if the corresponding payment method's Capture Mode is set to manual.
CancelRequest for abandoning a payment settlement. This action is only available if the corresponding payment method's Capture Mode is set to manual.
RefundOption to return (parts of) the captured amount. This action is only available if the corresponding payment transaction was captured before.
ReduceRequest for reducing the authorized payment amount partially. This action is only available if the corresponding payment method's Capture Mode is set to manual.

3.3 Synchronize Payment Transactions

The connector provides two options for manual synchronization of the payment states between Concardis and Intershop Commerce Management:

  • A REST endpoint
  • A Job (starting with version 1.1.4)

When a payment status was successfully synchronized with Concardis, the status is updated in ICM. Afterwards the order status is updated. In case the payment on Concardis side was successful, the order creation is continued at the point where it was broken. For failed payments the order is set to "PAYMENT_CANCELLED".

Orders which are pending on both sides (Concardis and ISH) cannot be fixed with that approach. In these cases there are abandoned baskets.

3.3.1 Job-Based Manual/Periodic Synchronization

To enable a periodic check if payments need to be synchronized, you have to configure a job in the SMC. Calling the startnode Start of pipeline SynchronizeConcardisPaymentsJob can be started manually or run regularly.

In the Attributes tab you can define after which time in the pending state (PendingSinceMins in minutes) a redirecting payment should be considered by the synchronization job and a status update from Concardis should be triggered.

The default value for the parameter PendingSinceMins is 30 minutes.

3.3.2 Manual Synchronization Using the REST Endpoint

For each order the administrator identified that it has an invalid state (payment status differs from Concardis), he has to copy the orderID from the Intershop Commerce Management URL (see screenshot below).

To trigger the synchronization call to Concardis, the administrator has to perform a REST request to the (temporary) API endpoint: /INTERSHOP/rest/WFS/inSPIRED-Site/inTRONICS/payment/concardis/synchronizations. The base URL is the same as in the ICM. In this example it is:  /INTERSHOP/rest/WFS/inSPIRED-Site/inTRONICS. Please use your own host and URL here.

Example call:

curl -X POST \
  http://<server>/<base-url>/payment/concardis/synchronizations \
  -u <order_manager>:<password> \
  -H 'Accept: text/plain' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{"orderId" : "jfYKAB2_wIMAAAFuFd0.wqdp"}'

Alternatively, you can use the attached collection in the REST client Postman: Synchronize.postman_collection.json

All variables have to be replaced with data that is valid for your system. Instead of the user parameter an authorization header can be used for getting access to the endpoint. The administrator must have permissions to manage orders. This can be checked here:

4 Data Handling

The following table describes transmitted data by the Concardis Service Connector from ICM to Concardis during the payment process:

DescriptionConcardis Payment Methods


AlipayBancontactCredit CardDirect DebitEPSGiroPayPaypalSofortWechatIdeal
Initial amountAmount for the transaction(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
Currency detailsCurrency code e.g. EUR/USD(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
Customer IdCustomer e-mail and customer ID(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
Merchant order idOrder reference generated by the merchant(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
ChannelTerminal used at time of order (MOTO: Mobile phone, ECOM: PC)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
Redirect URLsApplication URL for receiving callback response from Paygate(tick)(tick)(tick)(error)(tick)(tick)(tick)(tick)(tick)(tick)
Notification URNApplication URN for receiving transaction notifications from Paygate(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
Address detailsInvoice and shipping address details(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
Line items detailsDetails regarding product, shipping, discount, tax, gift card(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
Payment instrument IdTokenized identifier for customer account that can be stored and used for future transactions.(error)(error)(tick)(tick)(error)(error)(error)(error)(error)(error)
Credit card details

Card number, CVC, expiry date.

Sensitive data is handled via PayGate iframes only and is never stored at the merchant.

(error)(error)(tick)(error)(error)(error)(error)(error)(error)(error)
3-D Secure versionCredit card 3-D Secure version 1.0/2.0(error)(error)(tick)(error)(error)(error)(error)(error)(error)(error)
Browser informationBrowser details like javaEnabled, language, colorDepth, timezone, screenHeight, screenWidth, windowSize (error)(error)(tick)(error)(error)(error)(error)(error)(error)(error)
Account holder nameName of the account holder(error)(error)(error)(tick)(error)(error)(error)(error)(error)(error)
IBANInternational Bank Account Number(error)(error)(error)(tick)(error)(error)(error)(error)(error)(error)
BICBank Identifier Code(error)(error)(error)(question)(error)(error)(error)(error)(error)(error)
Direct debit typeOne time payment (single)
Stored account (first/recurring)
(error)(error)(error)(tick)(error)(error)(error)(error)(error)(error)


Flow Diagram

5 Limitations

5.1 Credit Card with Order Approval Service

Please be aware that Concardis Credit Card 3D Secure uses redirect after checkout. Intershop's current demo shop inSPIRED does not support a redirect after checkout if an order approval service in channel type intershop.SMBResponsive is enabled.

5.2 REST API Support

REST support for redirect after checkout is available starting with ICM 7.10.13.4 release.

5.3 New Headless Application Type

Starting from ICM 7.10.21, a new application type Progressive Web App is available and enabled for use with PWA 0.23.0 by default.

The new application type is not yet supported by the connector 1.10.x. Usage may lead to faulty handling in the PWA when using Credit Card or Direct Debit. To restore the old handling, the previous used application type has to be enabled again. To achieve this , the PWA 0.23.0 entry 

icmApplication: 'rest'

in the PWA file environment.ts has to  be set back to

icmApplication: '-'

The new headless application type will be supported out of the box with Concardis version 1.11 and higher in combination with PWA 0.25.0++.

PWA 0.24.0 and Concardis 1.10 are not compatible at all due to different feature set development states.

5.4 Partial Capture and Refund

Please be aware that partial capturing is only possible on Concardis side. Since the ICM only supports full capture in the commerce management, the refunds started from there cannot handle the fragmentation of the transactions. In case partial capturing via Concardis Merchant Interface is used, the refunding also has to be done there. The notifications will send updates to the ICM. If this is not considered and tried to refund an amount greater than the captured amount, the transaction goes into the final state "REFUND_FAILED".

5.5 Concardis Environments

It is important not to mix the types of the Concardis environment (Live/Sandbox). We recommend using the Sandbox environment in the testing system and the Live environment in the production system.

6 Noteworthy

  • The Concardis Payengine declines requests with already used order IDs.
  • Please note that hyphen signs in the order ID are not supported by some payment methods (e.g. Credit Card).
  • When using the Cancel button in the Sandbox redirect page, the Payengine sends "Success" to the ICM and the order is completed successfully.
  • Within Concardis test environment, eps is using the giropay processing engine and therefore displays "giropay" instead of "eps" within the Concardis sandbox. This is a known issue by Concardis and acknowledged.
  • When using the payment method PayPal in the Concardis sandbox, the failure button is missing in the simulated redirect. This is a known issue by Concardis and acknowledged.
  • In contrast to Concardis documentation initial order amounts of 1.11 or 111.11 will not trigger a negative response in the simulator. A charge-back on SEPA payments will be simulated.

7 Changelog

7.1 Version CONCARDIS/1.11.7

  • Added support for saving credit cards and SEPA direct debit accounts for later reuse and to allow merchant-initiated transactions

7.2 Version CONCARDIS/1.10.8

  • Fix CONCARDIS-384: Concardis payment is shown on zero money payment

7.3 Version CONCARDIS/1.10.7

  • Fix CONCARDIS-379: Header Accept Type incompatible with Concardis notifications

7.4 Version CONCARDIS/1.10.6

  • New payment method: Bancontact

7.5 Version CONCARDIS/1.9.8

7.6 Version CONCARDIS/1.9.7

  • New payment method: Alipay
  • New payment method: WeChat Pay
  • Improvement of address transmission with mapping of address fields

7.7 Version CONCARDIS/1.7.6

  • Fix CONCARDIS-298: Notification URLs are invalid when no ServerGroup is provided
  • Fix CONCARDIS-308: DirectDebit not usable without CreditCard

7.8 Version CONCARDIS/1.7.2

  • Support ICM 7.10.17.x
  • Provide access to prepared SEPA mandate text via REST

7.9 Version CONCARDIS/1.7.0

  • New payment method: SEPA Direct Debit
  • New payment method: Sofort
  • New feature: transmission of line items to Concardis
  • New feature: transmission of addresses to Concardis

7.10 Version CONCARDIS/1.3.2

  • Release including PayPal payment method
  • Support of 3DS 2.0 for credit card payments
  • New feature: support for Concardis Notifications API 2.0

7.11 Version CONCARDIS/1.1.5

  • Fix CONCARDIS-214: Specific REST request causes the ICM Storefront REST API to crash

7.12 Version CONCARDIS/1.1.4

  • New Feature: possibility to sync payment transactions with Concardis using a job.

7.13 Version CONCARDIS/1.1.3

  • New Feature: possibility to sync payment transactions with Concardis which is needed for some transactions until notification handling is available and integrated. See usage description in the Feature Overview.

7.14 Version CONCARDIS/1.1.2

  • Release including EPS, iDEAL and GiroPay payment methods

7.15 Version CONCARDIS/1.0.0

  • First Release including Credit Card payment method

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