3DS Server Card Ranges Processing

With each Versioning / Authentication request, the 3DS Server needs the information of the 3DS 2 enrolled card ranges in order to find out if the specific card is eligible for the 3DS 2 flow.

For this purpose, the 3DS Server sends Preparation Requests (PReq-s) to the schemes at a scheduled period of time in order to receive the 3DS 2 enrolled card ranges. The time interval at which the 3DS Server sends out Preparation Requests is configurable. The relevant property for this purpose is:

ds-client.preparation.request.interval.hours

The card ranges can then be stored in three different underlying storages: Database, EhCache or Redis. This is controlled by the:

threedsserver.session.storage.type

property. See details about the properties in the 3DS Server Configuration Properties.

Preparation Response (PRes) Processing

The 3DS Server processes the ranges in a way that:

  • In case card range is present in the PRes and not present in the underlying storage, it will insert it in the underlying storage
  • In case card range is present in the PRes and present in the underlying storage, it will update the one in the underlying storage
  • In case card range is not present in the PRes but it is present in the underlying storage, it will delete it in the underlying storage

The 3DS Server assigns an incremental revision number to each received preparation response and to all ranges received as part of it. In case overlapping ranges (from same scheme) are present, when resolving the ranges, the 3DS Server will give precedence to the one that has greater revision number, i.e. the one that was received sooner.

Caching of ranges

Since the ranges are checked each time a Versioning / Authentication Request is received, the 3DS Server caches the ranges in-memory for improved performance. When the 3DS Server starts up, it will load the card ranges before being available to accept HTTP requests. The 3DS Server will then check if there are new / updated ranges every 60 seconds in the underlying storage. If it identifies a change in the ranges in the underlying storage, it will reload the in-memory ranges. This interval can be configured differently with the following property:

threedsserver.session.storage.cache.card-range-data.cache-update-check.seconds

In-memory card ranges state

The state of the in-memory card ranges can be monitored by an actuator endpoint /card-ranges-cache exposed by the 3DS Server. This endpoint gives information about:

  • number of cache entries per scheme
  • timestamp of the last cache reload
  • number of seconds since last cache reload

Manual Preparation Request execution

It is possible to disable the scheduled execution of Preparation Requests by the 3DS Server and instead "manually" trigger sending Preparation Requests via a 3DS Server web service.

The 3DS Server web service for this purpose is mapped under /admin/start-preparation and handles HTTP POST requests.

Operation Query Parameters Response
start-preparation schemeId (String, not required) Empty response

The schemeId query parameter indicates the scheme to which the 3DS Server should send a Preparation Request. If it is not provided, the 3DS Server will send Preparation Requests to all schemes.

When a HTTP request is executed to this endpoint, the response will not wait for the preparation response to be received / processed, i.e the 3DS Server will only fire the Preparation Request(s) and return.

The execution / processing of the Preparation Request(s) should be followed via the logs.