-
Notifications
You must be signed in to change notification settings - Fork 2
4. Requirements
cristian.mihaita@maxcode.net edited this page Oct 8, 2019
·
2 revisions
This chapter describes the settings that are required for the successful integration of the iDIN Software Libraries into the Merchant’s system.
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.
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.
By adding this into the application’s startup file (Program.cs or Startup.cs) the usage of TLS 1.2 security protocol is enabled:
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;Below a sample appsettings file is shown. Please note that the Routing Service fingerprint is synonymous to the Acquirer fingerprint in Table 6.
{
"iDIN.Merchant.Library.Settings": {
"MerchantMerchantId": "1234567890",
"MerchantSubId": "0",
"MerchantReturnUrl": "http://example.com",
"MerchantAcquirerId": "42",
"AcquirerDirectoryUrl": "http://BankID.server/directory",
"AcquirerTransactionUrl": "http://BankID.server/transaction",
"AcquirerStatusUrl": "http://BankID.server/status",
"MerchantCertificateFingerprint": "824e7fa642552aed15dde42b6f4df856d7622d21",
"RoutingServiceCertificateFingerprint": "037084cee001b2f8f658d822ee5ea0a076a184e9",
"RoutingServiceAlternateCertificateFingerprint": "037084cee001b2f8f658d822ee5ea0a076a184e9", // OPTIONAL (advanced use)
"SAMLCertificateFingerprint": "824e7fa642552aed15dde42b6f4df856d7622d21",
"ServiceLogsEnabled": "true",
"ServiceLogsLocation": "D:\\home\\site\\wwwroot\\ServiceLogs",
"ServiceLogsPattern": "%Y-%M-%D\\%h%m%s.%f-%a.xml"
}
}
To settings can subsequently be loaded from the settings file, by passing the ApplicationSettings contract class, mapped to to the settings file, as follows:
var builder = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json");
var config = builder.Build();
var applicationConfig = config.GetSection("iDIN.Merchant.Library.Settings").Get<BankId.Merchant.Library.AppConfig.ApplicationSettings>();
BankID.Merchant.Library.Configuration merchantConfiguration = new BankID.Merchant.Library.Configuration(applicationConfig);The configuration can also be set-up from code. Please note that term Routing Service is synonymous to the Acquirer.
BankID.Merchant.Library.Configuration merchantConfiguration = 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"
);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);