Skip to content

4. Requirements

Jump to bottom
RPGThijssen edited this page Jun 28, 2019 · 4 revisions

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 .NET libraries

TLS 1.2 configuration:

By adding this into the application’s startup file (Global.asax or Startup.cs) the usage of TLS 1.2 security protocol is enabled and the connection to the Routing Service is possible.

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

Class that handles configuration settings:

public class Configuration
{
    public string EMandateContractId { get; private set; }
    public uint EMandateContractSubId { get; private set; }
    public string MerchantReturnUrl { get; private set; }
    public string SigningCertificateFingerprint { get; private set; }
    public string AcquirerCertificateFingerprint { get; private set; } 
    //Optional   
    public string AcquirerAlternateCertificateFingerprint { get; private set; }
    public string AcquirerUrlDirectoryReq { get; private set; }
    public string AcquirerUrlTransactionReq { get; private set; }
    public string AcquirerUrlStatusReq { get; private set; }
    public bool ServiceLogsEnabled { get; private set; }
    public string ServiceLogsLocation { get; private set; }
    public string ServiceLogsPattern { get; private set; }
}

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.SigningCertificate.Thumbprint" value="00000000000000000000000" />
    <add key="eMandates.AcquirerCertificate.Thumbprint" value="0000000000000000000000" />
    <!-- Optional -->
    <add key="eMandates.AcquirerAlternateCertificate.Thumbprint" value="0000000000000000000000" />
    <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.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.Load();
  • To setup configuration from code:
Configuration.Setup(new Configuration(
    eMandateContractId : "0000",
    eMandateContractSubId : 0,
    merchantReturnUrl : "https://web.shop/return",
    signingCertificateFingerprint : "000000000000000",
    acquirerCertificateFingerprint : "000000000000000",
    // Optional
    acquirerAlternateCertificateFingerprint : "000000000000000",
    acquirerUrlDirectoryReq : "https://mandate.bank.nl",
    acquirerUrlTransactionReq : "https://mandate.bank.nl",
    acquirerUrlStatusReq : "https://mandate.bank.nl",
    serviceLogsEnabled : true,
    serviceLogsLocation : "D:\\WebShop\\Logs",
    serviceLogsPattern : "%Y-%M-%D\\%h%m%s.%f-%a.xml"
));

By using both Load and Setup, the Configuration instance is available through Configuration.Instance global property.

The library also supports use of multiple Configuration instances, as follows:

      var coreConfiguration = new Configuration.Configuration(
              eMandateContractId: "0000",
    		eMandateContractSubId: 0,
    		merchantReturnUrl: "https://web.shop/returnForCore",
    		signingCertificateFingerprint: "000000000000000",
    		acquirerCertificateFingerprint: "000000000000000",
 		// Optional
    		acquirerAlternateCertificateFingerprint: "000000000000000",
    		acquirerUrlDirectoryReq: "https://mandate.bank.nl",
    		acquirerUrlTransactionReq: "https://mandate.bank.nl",
    		acquirerUrlStatusReq: "https://mandate.bank.nl",
    		serviceLogsEnabled: true,
    		serviceLogsLocation: "D:\\WebShop\\Logs",
    		serviceLogsPattern: "%Y-%M-%D\\%h%m%s.%f-%a.xml"
                );

       var b2bConfiguration = new Configuration.Configuration(
              eMandateContractId: "0001",
    		eMandateContractSubId: 0,
    		merchantReturnUrl: "https://web.shop/returnForB2B",
    		signingCertificateFingerprint: "000000000000000",
    		acquirerCertificateFingerprint: "000000000000000",
		// Optional
    		acquirerAlternateCertificateFingerprint: "000000000000000",
    		acquirerUrlDirectoryReq: "https://mandate.bank.nl",
    		acquirerUrlTransactionReq: "https://mandate.bank.nl",
    		acquirerUrlStatusReq: "https://mandate.bank.nl",
    		serviceLogsEnabled: true,
    		serviceLogsLocation: "D:\\WebShop\\Logs",
    		serviceLogsPattern: "%Y-%M-%D\\%h%m%s.%f-%a.xml"
                );

        var coreCommunicator = new CoreCommunicator(coreConfiguration);
        var b2bCommunicator = new B2BCommunicator(b2bConfiguration);

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.

In .NET, by default the library will try to load the certificates from the Certificate Store, using the fingerprints specified in the configuration. The library will first search the Local Machine store, followed by the Current User certificate store. In order to succeed, the host application's identity must have at least read permissions for the certificates.

Loading the certificates from locations other than the Certificate Store is possible by implementing the ICertificateLoader interface and sending an instance to the constructor of the Configuration class and using the Setup method. This will allow the library to load certificates from arbitrary locations, such as the file system or a database.

Please note that, for Windows .NET environments, the signing certificate should have a cryptographic service provider (CSP) reference to Microsoft Enhanced RSA and AES Cryptographic Provider to support the algorithms required by the eMandates and the underlying iDx protocol.

Clone this wiki locally