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 instance and call the etDirectory() method:
var response = new Communicator().GetDirectory();
if (response.IsError)
{
// show or log error message
}
else
{
// handle response: display list of issuing banks
}Here is the structure of the directory response:
public class DirectoryResponse
{
public bool IsError { get; }
public ErrorResponse Error { get; }
public DateTime DirectoryDateTimestamp { get; }
public Issuer[] Issuers { get; }
public string RawMessage { get; }
}An example on how to display the list of issuing banks in ASP.NET Razor views is presented below, once the Issuer list is retrieved:
@model BankID.Merchant.Library.SampleWebsite.Models.DirectoryModel
@Html.DropDownListFor(m => m.Issuers, new SelectList(Model.Issuers, "Id", "Name", "Country", 0), new { @class = "form-control", @name = "issuer" }) This will generate HTML mark-up for a drop-down list with all the available Issuers, grouped by Country:
When the Consumer selects an Issuer from this drop-down list, an Authentication Request can be performed, which is shown in the next step.
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:
var authenticationRequest = new BankID.Merchant.Library.AuthenticationRequest(
"entranceCode",
ServiceIds.Address | ServiceIds.DateOfBirth,
"issuerId"
);
var authenticationResponse = communicator.NewAuthenticationRequest(authenticationRequest);
if (authenticationResponse.IsError)
{
// display error: response.Error.ErrorMessage, response.Error.ErrorDetails
}
else
{
// redirect to response.IssuerAuthenticationURL
}Here is the structure of the authentication request:
public class AuthenticationRequest
public AssuranceLevel AssuranceLevel { get; }
public DateTime CreateDateTimestamp { get; }
public string EntranceCode { get; }
public TimeSpam? ExpirationPeriod { get; }
public string IssuerId { get; }
public string Language { get; }
public string MerchantReference { get; }
public ServiceIds ServiceId { get; }
}And this is the structure of the authentication response:
public class AuthenticationResponse
{
public bool IsError { get; }
public ErrorResponse Error { get; }
public Uri IssuerAuthenticationUrl { get; }
public string TransactionId { get; }
public DateTime TransactionCreateDateTimestamp { get; }
public string RawMessage { get; }
public string DocumentId { get; }
}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:
var statusRequest = new StatusRequest
{
TransactionId = "transactionId"
};
var statusResponse = communicator.GetResponse(statusRequest);
if (response.IsError)
{
// store error, or display it
}
else
{
if (response.Status.Equals(StatusResponse.Success))
{
// extract information from statusResponse.SamlResponse.AttributeStatements
}
}Here is the structure of the status request:
public class StatusRequest
{
public string TransactionId { get; }
}Here is the structure of the status response:
public class StatusResponse
{
public bool IsError { get; }
public ErrorResponse Error { get; }
public string TransactionId { get; }
public string Status { get; }
public DateTime? StatusDateTimestamp { get; }
public SamlResponse SamlResponse { get; }
public string RawMessage { get; }
}To perform an authentication request, instantiate a Communicator instance and call the NewAuthenticationRequest() method:
var req = new BankID.Merchant.Library.AuthenticationRequest(
"entranceCode",
ServiceIds.Sign,
"issuerId",
merchantDocumentId:"EDD32CB0CC1243F9A1B6418F983B1539"
//document identifier
);
var resp = communicator.NewAuthenticationRequest(authenticationRequest);