Skip to content

4. Requirements

Jump to bottom
cristian.mihaita@maxcode.net edited this page Sep 30, 2019 · 7 revisions

This chapter describes the settings that are required for the successful integration of the iDIN Software Libraries into the Merchant’s system.

4.1 System Settings

The following pre-requisites are needed on the system before integrating the iDIN Software Libraries:

  • It must be possible to make a TLS 1.2 connection to the Routing Service’s web service from the web server through port 443.
  • It must be possible to access the local machine certificate store during the installation of the certificates on the web server. The merchant certificate private key needs to be exportable.

4.2 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 (not all parameters are used in all libraries):

Parameter Description
Merchant.MerchantID This is the contract number for iDIN the Merchant received from its Acquirer after registration, and is used to unambiguously identify the Merchant.
This number is 10-digits long, where the first four digits are equal to the AcquirerID. Leading zeros must be included.
Merchant.SubID Unless agreed otherwise with the Acquirer, the Merchant has to use 0.
The SubID that uniquely defines the name and address of the Merchant to be used for iDIN, if operating under different brands or trading entities. The Merchant obtains the SubID from its Acquirer after registration for iDIN. A Merchant can request permission from the Acquirer to use one or more SubIDs.
Merchant.ReturnURL The web address provided by the Merchant in the transaction request that is used to redirect the Consumer back to the Merchant after completing the authentication in the Issuer domain. The URL does not necessarily begin with http:// or https://, it can also start with an app handler e.g. companyname-nl-service://.
.NET:
Merchant.Certificate.Fingerprint
.NET Core:
MerchantCertificateFingerprint
Java:
Merchant.Certificate.Alias
PHP:
Merchant.Certificate.File		 The configuration details of the certificate used to sign messages sent by the Merchant to the Acquirer’s Routing Service platform. It is also used by the Acquirer to authenticate incoming messages from the Merchant.
The .NET and .NET Core libraries use the fingerprint. For the Java library an alias must be provided that is configured in the Java Keystore. The PHP library works with a file configuration.
Note: For the PHP the path must lead to the private key file of the Merchant certificate (e.g. with extension .p12 or .pfx)
.NET:
SAML.Certificate.Fingerprint
.NET Core:
SAMLCertificateFingerprint
PHP:
SAML.Certificate.File		 The configuration details of the certificate of the Merchant used to decrypt the SAML Response. This can be the same as the details used for above certificate.
The .NET and .NET Core libraries use the fingerprint. The PHP library works with a file configuration.
Note: For the PHP the path must lead to the private key file of the Merchant certificate (e.g. with extension .p12 or .pfx)
Acquirer.AcquirerID Unique four-digit identifier of the Acquirer. These are equal to the first four digits of the MerchantID. Leading zeros must be included e.g. 0042
.NET:
RoutingService.Certificate.Fingerprint
.NET Core:
RoutingServiceCertificateFingerprint
Java:
Acquirer.Certificate.Alias
PHP:
RoutingService.Certificate.File		 The configuration details of the certificate used to validate incoming messages from Acquirer (a.k.a. Routing Service) to the Merchant’s application.
For .NET, .NET Core and PHP the term Routing Service is used, but this is the same as the Acquirer.
The .NET and .NET Core libraries use the fingerprint. For the Java library an alias must be provided that is configured in the Java Keystore. The PHP library works with a file configuration.
Note: For the PHP the path must lead to the public certificate of the Acquirer/Routing Service (e.g. with extension .cer)
.NET:
RoutingService.AlternateCertificate.Fingerprint (optional)
.NET Core:
RoutingServiceAlternateCertificateFingerprint (optional)
Java:
Acquirer.AlternateCertificate.Alias		 The fingerprint of the alternate certificate used to validate incoming messages from the Acquirer to the Merchant’s application. This feature is currently available only for the .NET, .NET Core and Java software libraries.
Acquirer.DirectoryURL The web address of the Acquirer’s Routing service platform from where the list of Issuers is retrieved (using a directory request).
Note: The directory URL, transaction URL and status URL can be the same.
Acquirer.TransactionURL The web address of the Acquirer’s Routing Service platform where the transactions (authentication requests) are initiated.
Note: The directory URL, transaction URL and status URL can be the same.
Acquirer.StatusURL The web address of the Acquirer’s Routing Service platform to where the library sends status request messages.
Note: The directory URL, transaction URL and status URL can be the same.
Logs.Enabled Enable the saving of service logs (all raw messages exchanged by the library). Either “true” or “false”.
ServiceLogs.Enabled Enable the saving of service logs (all raw messages exchanged by the library). Either “true” or “false”.
ServiceLogs.Location The disk location where the request messages sent by the library and the response messages received from the Acquirer will be logged.
ServiceLogs.Pattern 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, a 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

In the next sections the approach for the configuration is explained, on a platform-by-platform basis.

4.2.2 .NET Library settings

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:

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

Below a sample configuration file is shown. Please note that the Routing Service fingerprint is synonymous to the Acquirer fingerprint in Table 6.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
  </startup>
  <appSettings>
    <add key="BankID.Merchant.MerchantID" value="0042567890" />
    <add key="BankID.Merchant.SubID" value="0" />
    <add key="BankID.Merchant.ReturnUrl" value="http://example.com/return" />

    <add key="BankID.Merchant.AcquirerID" value="0042" />
    <add key="BankID.Acquirer.DirectoryUrl" value="http://BankID.server/directory" />
    <add key="BankID.Acquirer.TransactionUrl" value="http://BankID.server/transaction" />
    <add key="BankID.Acquirer.StatusUrl" value="http://BankID.server/status" />

    <add key="BankID.Merchant.Certificate.Fingerprint" value="824e7fa642552aed15dde42b6f4df856d7622d21" />
    <add key="BankID.RoutingService.Certificate.Fingerprint" value="037084cee001b2f8f658d822ee5ea0a076a184e9" />
<add key="BankID.RoutingService.AlternateCertificate.Fingerprint" value="037084cee001b2f8f658d822ee5ea0a076a184e9" /> <!-- OPTIONAL (advanced use) -->
    <add key="BankID.SAML.Certificate.Fingerprint" value="824e7fa642552aed15dde42b6f4df856d7622d21" />
    <add key="BankID.ServiceLogs.Enabled" value="true" />
    <add key="BankID.ServiceLogs.Location" value="d:\ApplicationData\BankID.Merchant.Website\ServiceLogs" />
    <add key="BankID.ServiceLogs.Pattern" value="%Y-%M-%D\%h%m%s.%f-%a.xml" />
  </appSettings>
</configuration>

To settings can subsequently be loaded from the configuration file as follows:

Configuration.Load();

The configuration can also be set-up from code. Please note that term Routing Service is synonymous to the Acquirer.

BankID.Merchant.Library.Configuration.Setup(
                new BankID.Merchant.Library.Configuration(
                    "acquirerId",
                    "merchantId",
                    new Uri("merchantReturnUrl"),
                    new Uri("acquirerDirectoryUrl"),
                    new Uri("acquirerTransactionUrl"),
                    new Uri("acquirerStatusUri"),
                    "merchantCertificateFingerprint",
                    "routingServiceCertificateFingerprint",
			//Can be String, empty or Null
			"routingServiceAlternateCertificateFingerprint",
                    "samlCertificateFingerprint",
                    "serviceLogsLocation",
                    true,
                    "serviceLogsPattern"));

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

4.2.2.1 .NET Library settings to support multiple Merchants

The library also supports use of multiple Configuration instances. This can be useful when multiple merchants are to be configured. Configuring two Merchants configurations can be done as follows:

var firstMerchantConfiguration = new BankID.Merchant.Library.Configuration(
                acquirerId: "acquirerId1",
                merchantId: "merchantId1",
                merchantReturnUrl: new Uri("merchantReturnUrl1"),
                acquirerDirectoryUrl: new Uri("acquirerDirectoryUrl1"),
                acquirerTransactionUrl: new Uri("acquirerTransactionUrl1"),
                acquirerStatusUrl: new Uri("acquirerStatusUri1"),
                merchantCertificateFingerprint: "merchantCertificateFingerprint1",
                routingServiceCertificateFingerprint:       "routingServiceCertificateFingerprint1",
		  //Can be String, empty or Null
		   alternateRoutingServiceCertificateFingerprint: "alternateRoutingServiceCertificateFingerprint",
                samlCertificateFingerprint: "samlCertificateFingerprint1",
                serviceLogsLocation: "serviceLogsLocation1",
                serviceLogsEnabled: true,
                serviceLogsPattern: "serviceLogsPattern1"
                );
var secondMerchantConfiguration = new BankID.Merchant.Library.Configuration(
              acquirerId: "acquirerId2",
              merchantId: "merchantId2",
              merchantReturnUrl: new Uri("merchantReturnUrl2"),
              acquirerDirectoryUrl: new Uri("acquirerDirectoryUrl2"),
              acquirerTransactionUrl: new Uri("acquirerTransactionUrl2"),
              acquirerStatusUrl: new Uri("acquirerStatusUri2"),
              merchantCertificateFingerprint: "merchantCertificateFingerprint2",
              routingServiceCertificateFingerprint: "routingServiceCertificateFingerprint2",
		 //Can be String, empty or Null
		 alternateRoutingServiceCertificateFingerprint: " alternateRoutingServiceCertificateFingerprint2",

              samlCertificateFingerprint: "samlCertificateFingerprint2",
              serviceLogsLocation: "serviceLogsLocation2",
              serviceLogsEnabled: true,
              serviceLogsPattern: "serviceLogsPattern2"
              );
var communicator = new BankID.Merchant.Library.Communicator(firstMerchantConfiguration);

var secondCommunicator = new BankID.Merchant.Library.Communicator(secondMerchantConfiguration);

Clone this wiki locally