Repository navigation
3. Generic integration guidelines
When integrating the iDIN Software Libraries into your solution, the guidelines in the upcoming sections should be followed.
To be able to function, the library needs to have access to three certificates:
- Merchant’s certificate: This is the certificate owned by the Merchant. It’s the private certificate used to sign messages sent by the Merchant to the Acquirer's Routing Service platform. Its public key is also used by the Acquirer to authenticate incoming messages from the Merchant. The Merchant certificate must be in PKCS#12 format which has the extension .p12 or .pfx;
- The SAML certificate: This is the certificate owned by the Merchant. Its public key is used by the Issuer to encrypt information. The Merchant can then use the private key to decrypt that information. The SAML certificate must be in PKCS#12 format which has the extension .p12 or .pfx;
- The Acquirer’s (a.k.a. Routing Service’s) public certificate: This is the public certificate used to authenticate incoming messages from the Acquirer. The library only needs its public key. The public certificate must be in PEM format (base64 ASCII) and typically has the file extension .cer, .crt or .pem.
The certificate that is used to sign the messages (1), and the certificate that is used by the Issuer to encrypt information (2) may be the same certificate. Hence, depending on your preferences you can use two or the same certificate for both (1) and (2).
Certificates can be bought from a Certificate Authority, or they can be created yourself with for example OpenSSL. How to safely store and maintain certificates is beyond the scope of this manual. Examples to create a private key, public certificate and PKCS#12 file are provided below.
Note: The requirements on the certificates and more information about how these are used within iDIN can be found in the Merchant Implementation Guidelines in §10.3 - §10.6.
- The private key should never be shared with other parties
- This private key does not have to be loaded in the library directly
- The private key has a length of 2048 bit and in encrypted with a password
The following OpenSSL command can be used to create a private key:
openssl genrsa -aes128 -out YourPrivateKey.pem -passout pass:[password] 2048
Note: Please be wary when copying directly from this PDF document, some characters may not be properly copied causing the command to not work (e.g. wrong type of ‘-‘).
- The public certificate is created from the private key created earlier;
- The expiration period of the public certificate must be a minimum of 1 year, and a maximum of 5 years;
- When creating a public certificate, the user is asked to fill in information about the country name, state/province, city, organisation name, unit name, common name and email address. These parameters can be chosen at will;
- The public certificate(s) needs to be uploaded in the portal of the Routing Service;
- For the output the extension .cer has been chosen, however this may also be .crt or .pem.
The following OpenSSL can be used to create the public certificate
openssl req -x509 -sha256 -new -key YourPrivateKey.pem -passin pass:[password] -days 1825 -out YourPublicCertifiate.cer
Note: Please be wary when copying directly from this PDF document, some characters may not be properly copied causing the command to not work (e.g. wrong type of ‘-‘).
- The PKCS#12 contains both the private key and the public certificate, therefore it should also never be shared with other parties;
- The PKCS#12 files (Merchant/SAML certificates) should be imported in the Software Library;
- For the output the extension .p12 has been chosen, however this may also be .pfx.
The following OpenSSL can be used to create the PKCS#12 file:
openssl pkcs12 -export -out YourPKCS12File.p12 -inkey YourPrivateKey.pem -password pass:[password] -in YourPublicCertificate.cer
Note 1: Please be wary when copying directly from this PDF document, some characters may not be properly copied causing the command to not work (e.g. wrong type of ‘-‘).
Note 2: For the .NET library, the PKCS#12 file for the Merchant certificate is to be created differently, which is explained in §3.1.2.1.
For PHP, the Merchant certificate must be in PKCS#12 format (.p12 or .pfx extension) and the Acquirer’s certificate in PEM format (typically with .pem or .cer or .crt extensions). They need to be located in a path that is readable by the web server and PHP interpreter. The php.ini can be modified to add the directory or directories where the certificates are located to the global PHP includes (http://php.net/manual/en/ini.core.php#ini.include-path), in order to only specify the file name in the configuration file. As such, the PHP version of the library needs path names for configuration options related to certificates:
- Merchant certificate file: The file name to be used as Merchant certificate (PKCS#12 format);
- Acquirer’s (a.k.a. Routing Service) certificate file: The file name to be used as Acquirer certificate (PEM format);
- SAML certificate file: The file name to be used as SAML certificate (PKCS#12 format).
The PHP version of the iDIN Merchant Library requires three PHP extensions to be enabled:
- php_curl: This is required so that the library can make HTTP requests;
- php_openssl: This is required for the library to correctly handle loading certificates, signing messages and checking the signatures of incoming message. OpenSSL 1.0 or higher should be used;
- php_mcrypt: this is required for decryption routines (some fields in the status response are encrypted using AES-256).
These extensions can all be enabled in the php.ini file.
In the package, there is a directory named "Library/PHP". This directory can be copied to any directory on the disk that is accessible by the webserver, for example "C:\php\bankid_library". In the PHP project, just require "C:\php\php_library\vendor\autoload.php" and the classes in the library can be directly used. Also, add an XML configuration file to the project, using the same structure as .NET or Java. Below are a few screenshots which show how to do this in Netbeans:
Require LIBRARY_DIRECTORY/vendor/autoload.php and write code using the library:
The library can now be used to perform requests. Chapter 0 in this manual provides more information on how to perform these operations. The following code snippet can be copied/pasted into a new console application project to start using the library right away. Make sure the namespace and class names correspond to the names chosen when the project was set-up, and change the configuration settings as necessary (check Section 4.2 in this manual for more information about specific settings)
<?php
require 'c:\php\bankid_library\vendor\autoload.php';
use BankId\Merchant\Library\Communicator;
use BankId\Merchant\Library\Configuration;
$config = new Configuration();
$config->set(
'111111111',
'0',
'https://my.web.shop/transaction/return',
'https://my.bank/url_for_directory_requests',
'https://my.bank/url_for_transaction_requests',
'https://my.bank/url_for_status_requests',
'my_certificate.p12',
'routing_service_certificate.cer',
'my_saml_certificate.p12',
NULL,
'password_for_my_certificate_private_key',
NULL,
NULL,
'password_for_my_saml_certificate_private_key',
'D:\My.Logs\ServiceLogs',
TRUE,
'%Y-%M-%D\%h%m%s.%f-%a.xml');
Configuration::defaultInstance()->setup($config);
$communicator = new Communicator();
$response = $communicator->getDirectory();
if ($response->getIsError()) {
print 'error = ' . $response->getErrorResponse()->getMessage();
}
else {
foreach ($response->getIssuers() as $issuer) {
print $issuer->getCountry() . ' ' . $issuer->getName() . ' ' . $issuer->getID();
}