Repository navigation
5. Integration Workflow
This chapter contains integration guidelines and sample code for each of the main operations specific to the iDIN service.
To facilitate an integration process, the sample code from the package illustrates how a web application could integrate with an iDIN library. Parts of this code are presented below as an example for each of the iDIN service specific operations.
The sample code is a basic website integration with the libraries where the user can choose an Issuer, initiate a transaction and request the transaction status.
The Directory request involves querying the Acquirer, so it returns a list of Issuers. A customer on the website will then select its Issuer he/she has an account with, and the process continues. When issuing the request, no additional parameters have to be specified.
It is not allowed to perform the Directory protocol for each transaction. Because the list of Issuers only changes occasionally, it is sufficient to execute the Directory protocol on a weekly basis and check if the list has changed based on the DirectoryDateTimestamp. If the Issuer list has changed, the latest version has to be saved and used for any subsequent transaction. Routing Services will normally also inform all Merchants (e.g. by email) about changes in their Issuer list. The Directory protocol should at least be executed once a week.
The response will include the following parameters:
- IsError: Field that allows to check if an error occurred;
- Error: An ErrorResponse object containing error information, if one occurred
- DirectoryDateTimestamp: This field contains the date when the directory was last updated by the Acquirer’s Routing Service;
- Issuers: The returned list of Issuers, each described by an identifier, country name and bank name;
- RawMessage: The actual XML message received from the Routing Service.
Examples are presented below on of how to perform a directory request, check the response and display the result on each of the supported platforms.
To perform a directory request, instantiate a Communicator object, and call the getDirectory() method:
$comm = new Communicator();
$response = $comm->getDirectory();
if ($response->getIsError()) {
// log error, show error message
}
else {
// handle response: display list of issuing banks
}Here is the structure of the directory response:
class DirectoryResponse {
public function getIsError();
public function getErrorResponse();
public function getDirectoryDateTimestamp();
public function getIssuers();
public function getRawMessage();
}Once retrieved, here is an example of how to display the list of issuing banks using PHP:
<!--
$Model = $comm->getDirectory();
-->
<select class="form-control">
<option>Choose a bank</option>
<?php foreach ($Model->getIssuersByCountry() as $key => $value) { ?>
<optgroup label="<?php echo $key; ?>">
<?php foreach ($value as $issuer) { ?>
<option value="<?php echo $issuer->getID(); ?>">
<?php echo $issuer->getName(); ?>
</option>
<?php } ?>
</optgroup>
<?php } ?>
</select>This will generate HTML mark-up for a drop-down list with all the available Issuers, grouped by Country:
The process of starting a new authentication request is initiated on the Merchant’s website by the Consumer. The Merchant enters the information in the message and this information set is then completed with Acquirer information (by the Routing Service) and sent to the Validation Service/Issuer. The library simplifies this by requiring input for only a limited number of fields, with the rest being filled in automatically, and handles the process in the NewAuthenticationRequest() method.
Request parameters:
- IssuerId: The identity of the Issuer that was selected by the Consumer;
- Language: This field enables the Issuer’s website or mobile app to select the Consumer’s preferred language (e.g. the language that was selected on the Merchant’s website or mobile app), if this language is supported by the Issuer’s website or mobile app. The code list according to ISO 639-1. (e.g. ‘en’ for English, ‘nl’ for Dutch) should be used. If a non-supported or non-existing language is entered, the standard language of the Issuer is used;
- ExpirationPeriod: If specified, the Consumer must approve the transaction in the specified number of seconds. The Consumer must complete the transaction within this period; otherwise, the Issuer sets the transaction status to “Expired”. Minimum is 60 seconds and maximum and default is 300 seconds. The Merchant does not have to enter a value for this field. It is recommended for Merchants to leave the ExpirationPeriod empty;
- RequestedServiceId: ID of the list of services provided. Please refer to the iDIN Merchant Implementation Guidelines document for more information;
- MerchantReference: Unique identifier for this transaction, set by the Merchant;
- AssuranceLevel: Describes the minimum level of assurance required; can be AssuranceLevel.Loa3.
Response parameters:
- IsError: True if there was an error, or false if the response was received without errors;
- Error: An ErrorResponse object containing error information, of one occurred;
- IssuerAuthenticationUrl: An URL given by the Issuer, to which the Merchant must redirect the Consumer, so they can authenticate this transaction;
- TransactionId: The identifier assigned by the Routing Service for this transaction. This parameter is required to request the status in a later stage, see Section 5.3;
- TransactionCreateDateTimestamp: The specific date and time when this transaction was registered by the Routing Service of the Acquirer;
- RawMessage: The actual XML message received from the Routing Service.
Below examples are presented on how to perform a new authentication request and check the response, for each of the supported platforms.
To perform an authentication request, instantiate a Communicator instance and call the newAuthenticationRequest() method:
$comm = new Communicator();
$ar = new AuthenticationRequest();
$ar->setAssuranceLevel(AssuranceLevel::$Loa3);
$ar->setEntranceCode('entranceCode');
$ar->setExpirationPeriod(NULL);
$ar->setIssuerID('ISSUERID');
$ar->setLanguage('nl');
$ar->setMerchantReference('merchantReference');
$ar->setServiceID(ServiceIds::$IsEighteenOrOlder | ServiceIds::$Address);
$response = $comm->newAuthenticationRequest($ar);
if ($response->getIsError()) {
// log error, show error message
}
else {
// redirect to $response->getIssuerAuthenticationURL()
}Here is the structure of the authentication request:
class AuthenticationRequest {
public function setEntranceCode($entranceCode);
public function setLanguage($language);
public function setExpirationPeriod($expirationPeriod);
public function setMerchantReference($merchantReference);
public function setServiceID($serviceID);
public function setAssuranceLevel($assuranceLevel);
public function setDocumentID($documentID);
}And this is the structure of the authentication response:
class AuthenticationResponse {
public function getIsError();
public function getErrorResponse();
public function getIssuerAuthenticationURL();
public function getTransactionID();
public function getTransactionCreateDateTimestamp();
public function getRawMessage();
}To retrieve requested information after a successful authentication request and response, the Merchant will start the status protocol by sending a status request to the Routing Service.
If no errors are encountered, the Routing Service will respond with the full Assertion received from the Validation Service, containing the requested information, but encrypted. The library uses the SAML certificate to decrypt that information and returns a SamlResponse object.
Request parameters:
- TransactionId: the transaction ID.
Response parameters:
- IsError: True if there was an error, or false if the response was received without errors.
- Error: An ErrorResponse object that contains error-related information if an error occurs, or null if there was no error.
- TransactionId: Transaction ID for this specific transaction;
-
Status: String that contains the status message and can be one of the following:
- Success: Positive result; the transaction is or has been executed;
- Cancelled: Negative result due to cancellation by Consumer; the transaction will not be executed;
- Expired: Negative result due to expiration of the transaction; the transaction will not be executed. This status is only given when the Consumer has not approved the transaction within the Expiration period;
- Failure: Negative result due to other reasons; the transaction will not be executed;
- Open: Final result not yet known;
- Pending: Transaction has not yet been completed;
- StatusDateTimestamp: Field set to the time of the transaction’s status change;
- RawMessage: The actual XML message received from the Routing Service;
- SamlResponse: An object that contains more information. This field is only present when Status is “Success”.
Here are the fields in the SAML response:
- TransactionId: Identification of the current transaction;
- MerchantReference: The merchant reference, set by the Merchant;
- AcquirerId: Contains the ID of the party that created the SAML Response, which is always the Acquirer’s Routing Service;
- Version: SAML version;
-
Attributes: A key-value map of all the decrypted attributes that are provided by the Issuer. Depending on what service the Merchant has requested one or more attributes are returned. Here are a few examples (please refer to the iDIN Merchant Implementation Guidelines document for more information and formatting rules):
- consumer.gender: Gender of Consumer;
- consumer.initials: Initials of Consumer;
- consumer.18orolder: Specifies whether the Consumer is 18 or older;
- BankID.DeliveredServiceID: Returned to the Merchant in the Response to indicate which requested attributes are delivered conform the minimal set as defined in the Merchant Implementation Guidelines;
-
SamlStatus: A structure further detailing the response status. This contains:
- StatusMessage: A general-purpose message. Determined by Routing or Validation Service;
- StatusCodeFirstLevel: A status code representing the status of the SAML request;
- StatusCodeSecondLevel: A status code representing the status of the handling of DeliveredServiceId. If not all the attributes can be provided conform a specified set as specified in Section 5.5 of the Merchant Implementation Guidelines by the Validation Service, this field is set to “urn:nl:bvn:bankid:1.0:status:IncompleteAttributeSet”.
A Merchant may only initiate the getResponse() method when the Consumer is successfully redirected back to the Merchant by the Issuer using the Merchant Return URL (that the Merchant has configured in the configuration file).
The SAML Assertion issued by the Validation Service is only valid for 30 seconds. From the moment that the Consumer has been successfully redirected to the Merchant up to the time the Assertion is expired, the Merchant can make status requests. However, the Merchant should only perform more than one status request if it has received a timeout from the Routing Service (see Chapter 9 of the iDIN Merchant Implementation Guidelines for more detail). The Merchant is not allowed to perform any more status requests once it received notification from the Validation Service that the Assertion has expired. Merchants will be perceived as committing undesirable actions if they use the getResponse() method more than the above described limitation, as doing so places unnecessarily heavy demands on the Acquirer’s and Issuer’s system. Below examples are presented on how to perform requests and check the responses, for each of the supported platforms.
To perform the authentication status request, instantiate a Communicator instance and call the getResponse() method:
$comm = new Communicator();
$sr = new StatusRequest();
$sr->setTransactionID('1234567890');
$response = $comm->getResponse($sr);
if ($response->getIsError()) {
// log error, show error message
}
else {
if (strcmp($response->getStatus() == StatusResponse::$Success) == 0) {
// extract information from $response->getSamlResponse()
}
}Here is the structure of the status request:
class StatusRequest {
public function setTransactionID($entranceCode);
}Here is the structure of the status response:
class StatusResponse {
public function getIsError();
public function getErrorResponse();
public function getTransactionID();
public function getStatus();
public function getStatusDateTimestamp();
public function getRawMessage();
public function getSamlResponse();
}To perform an authentication request, instantiate a Communicator instance and call the newAuthenticationRequest() method:
$comm = new Communicator();
$ar = new AuthenticationRequest();
$ar->setAssuranceLevel(AssuranceLevel::$Loa3);
$ar->setEntranceCode('entranceCode');
$ar->setExpirationPeriod(NULL);
$ar->setIssuerID('ISSUERID');
$ar->setLanguage('nl');
$ar->setMerchantReference('merchantReference');
$ar->setServiceID(ServiceIds::$Sign);
$ar->setDocumentID(' EDD32CB0CC1243F9A1B6418F983B1539');//document identifier
$response = $comm->newAuthenticationRequest($ar);