4. Requirements

This chapter describes the settings that are required for the successful integration of the eMandate Creditor Libraries into the Creditor’s system.

System Settings

The following pre-requisites are needed on your system before integrating the eMandate Creditor Libraries:

• It must be possible to make an SSL connection to the Routing Service’s web service from the web server through port 443.
• It must be possible to access to the local machine certificate store during the installation of the certificates on the web server.

Library Settings

The configuration of the libraries is possible at runtime during initialization or via a configuration file (development platform specific).

The following parameters are configurable in the libraries configuration:

• eMandates contract id – given by the Creditor Bank to the Creditor to unambiguously identify the Creditor when communicating with the Creditor Bank platform.
• eMandates contract subreference id – given by the Creditor Bank to the Creditor to unambiguously identity the branch or trading entity of the Creditor. This parameter is optional.
• merchant return URL – the web address provided by the Creditor in the transaction request that is used to redirect the Debtor back to the Creditor after completing the authorization.
• signing certificate fingerprint – the fingerprint of the private certificate used to sign messages sent by Creditor to the Creditor Bank’s Routing Service platform, also used by the Creditor Bank to authenticate incoming messages from Creditor.
• acquirer’s directory request URL– the web address of the Creditor Bank’s Routing service platform from where the list of Debtor Banks is retrieved.
• acquirer’s transaction request URL – the web address of the Creditor Bank’s Routing Service platform where the transactions are initiated.
• acquirer’s status request URL – the web address of the Creditor Bank’s Routing Service platform to where the library send status request messages.
• acquirer’s certificate fingerprint – the fingerprint of the certificate used to validate incoming messages from Creditor Bank to Creditor application.
• acquirer’s alternative certificate fingerprint (optional) – the fingerprint of the alternative certificate used to validate incoming messages from Creditor Bank to Creditor application.
• enable saving service log files – Enable the saving of service logs (all raw messages exchanged by the library).
• location of service log files – The disk location where the request messages sent by the library and the response messages received from the Acquirer will be logged.
• pattern for service log file names – A string describing what the file names of the service logs should look like, so they can be organized in different folders, by year, month, day, time of day and type of message. As an example pattern in the form of %Y-%M-%D\%h%m%s.%f-%a.xml will create a directory for each day (in the form on 2014-01-20), and a file for each operation in the form of 102045.924-AcquirerTrxReq.xml. When creating a pattern, you can use the following placeholders:
  • %Y = current year
  • %M = current month
  • %D = current day
  • %h = current hour
  • %m = current minute
  • %s = current second
  • %f = current millisecond
  • %a = current action.

Following, you can find the approaches for configuring the Java libraries.

This is the class that handles configuration settings:

public class Configuration {
    private String eMandateContractId;
    private int eMandateContractSubId;
    private String merchantReturnUrl;
    private String keyStoreLocation;
    private String keyStorePassword;
    private String signingCertificateAlias;
    private String signingCertificatePassword;
    private String acquirerCertificateAlias;
    private String acquirerAlternateCertificateAlias;
    private String acquirerUrl_DirectoryReq;
    private String acquirerUrl_TransactionReq;
    private String acquirerUrl_StatusReq;
    private boolean serviceLogsEnabled;
    private String serviceLogsLocation;
    private String serviceLogsPattern;
}

Sample configuration file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<appSettings>
  <add key="eMandates.Contract.Id" value="0123456789" />
  <add key="eMandates.Contract.SubId" value="0" />
  <add key="eMandates.Merchant.ReturnUrl" value="https://webshop.nl/return" />
  <add key="eMandates.KeyStore.Location" value="certificatestore.jks" />
  <add key="eMandates.KeyStore.Password" value="password" />
  <add key="eMandates.SigningCertificate.Alias" value="client" />
  <add key="eMandates.SigningCertificate.Password" value="password" />
  <add key="eMandates.AcquirerCertificate.Alias" value="server" />
  <add key="eMandates.AcquirerAlternateCertificate.Alias" value="" />
  <add key="eMandates.Acquirer.DirectoryRequestUrl" value="https://mandate.bank.nl" />
  <add key="eMandates.Acquirer.TransactionRequestUrl" value="https://mandate.bank.nl" />
  <add key="eMandates.Acquirer.StatusRequestUrl"         value="https://mandate.bank.nl" />
  <add key="eMandates.Logs.Enabled" value="true" />
  <add key="eMandates.ServiceLogs.Enabled" value="true" />
  <add key="eMandates.ServiceLogs.Location" value="D:\WebShop\ServiceLogs" />
  <add key="eMandates.ServiceLogs.Pattern" value="%Y-%M-%D\%h%m%s.%f-%a.xml" />
</appSettings>
</configuration>

Usage:

To load settings from configuration file:

            Configuration.defaultInstance()
                .Load(
                    getServletContext().getResourceAsStream("/config.xml")
                );

To setup configuration from code:

         Configuration.defaultInstance().Setup(new Configuration(
              "0000000000"
            , 0
            , "https://web.shop/return"
            , "certificatestore.jks"
            , "password"
            , "client"
            , "password"
            , "server"
            , "serverAlternative"
            , "https://mandate.bank.nl"
            , "https://mandate.bank.nl"
            , "https://mandate.bank.nl"
            , true
            , true
            , "D:\\WebShop\\Logs"
            , "%Y-%M-%D\\%h%m%s.%f-%a.xml"
        ));

To create a new configuration object in order to pass it to the CoreCommunicator or B2bCommunicator:

• use the clone method and the setters (e.g. if you need a similar configuration to an already existing one):

 	Configuration newConfig = Configuration.defaultInstance().clone();

• use the constructor in which you pass the String keyStoreLocation – this way you can load your keyStore from the classpath

new Configuration(
              "0000000000"
            , 0
            , "https://web.shop/return"
            , "certificatestore.jks" // String keyStoreLocation
            , "password"
            , "client"
            , "password"
            , "server"
            , "serverAlternative"
            , "https://mandate.bank.nl"
            , "https://mandate.bank.nl"
            , "https://mandate.bank.nl"
            , true
            , true
            , "D:\\WebShop\\Logs"
            , "%Y-%M-%D\\%h%m%s.%f-%a.xml"
          ));

• use the constructor in which you pass the InputStream keyStore (e.g. if you want to load your keyStore from a different location than the classpath, you and load it as a InputStream and pass it as a parameter)

new Configuration(
              "0000000000"
            , 0
            , "https://web.shop/return"
          , keyStore // InputStream keyStore
            , "password"
            , "client"
            , "password"
            , "server"
            , "serverAlternative"
            , "https://mandate.bank.nl"
            , "https://mandate.bank.nl"
            , "https://mandate.bank.nl"
            , true
            , true
            , "D:\\WebShop\\Logs"
            , "%Y-%M-%D\\%h%m%s.%f-%a.xml"
       ));

Certificates

In order to be able to function, the library needs to have access to two certificates - the Creditor certificate and the Creditor bank's public certificate.

The creditor certificate is the private certificate used to sign messages sent by the Creditor to the Creditor Bank's Routing Service platform. Its public key is also used by the Creditor Bank to authenticate incoming messages from the Creditor.

The Creditor bank public certificate is the certificate used to authenticate incoming messages from the Creditor Bank. The library only needs its public key.

Note: How to obtain these certificates is outside the scope of this wiki, more details are available in the eMandates Creditor Implementation Guidelines Core and B2B - 11.4 Creating a key pair

Java certificates are stored in Java keystores, which are files on the disk – they are protected by a password and have the .jks extension. You need to import certificates into the keystore using the keytool application, installed as part of the Java Development Kit. Creating and managing keystores is outside of the scope of this manual, please consult the Oracle documentation. There, you can find more extensive documentation on this tool, examples on how to create a keystore, a private/public key pair etc. Here are some examples on how to use the keytool application for a few common scenarios:

• Importing an existing certificate into a keystore and assigning it an alias: keytool -import -alias "server" -file server.cer -keystore .\certificates.jks
• Listing certificates in a keystore: keytool -list -keystore .\certificates.jks
• Importing a PKCS12 certificate, together with the private key, into a keystore: keytool -importkeystore -destkeystore .\certificates.jks -srckeystore privatekey.p12 -srcstoretype pkcs12

The Java eMandates Creditor Library needs to access a keystore located in the Java classpath. Furthermore, the private key of a certificate can also be protected by a password. As such, the Java library has 3 more configuration options:

• keystore location – a file path and name, accessible to the library, which is the Java keystore where the certificates are stored.
• keystore password – the password used to access the keystore.
• signing certificate password – the password used to access the private key of the signing certificate.

Both the signing certificate and the acquirer’s certificate need to be imported in the same keystore. When doing that, you must also provide an alias for each of them, and while the .NET version uses certificate thumbprints to search for existing certificates, the Java version uses these aliases. So certificate thumbprints in the .NET version are certificate aliases in the Java version:

• signing certificate alias – the alias assigned to the signing certificate in the keystore. This could be the alias you supplied explicitly when importing an existing certificate in the keystore, or it could be an alias automatically assigned by the keytool application.
• acquirer certificate alias – the alias assigned to the acquirer certificate in the keystore. This could be the alias you supplied explicitly when importing an existing certificate in the keystore, or it could be an alias automatically assigned by the keytool application.