SAFE2 Data Delivery Interface

The specification on how the data should be reported to the Danish Gambling Authority is called Standard Records. The DDI follows Standard Records and adds additional functionality, such as a possibility to send the data in json format.

Even though Danske Spil game suppliers have to report gaming data to the DDI, all the information on the game details, formatting, related fields, etc is specified in the Standard Records and not the DDI. Hence the DDI can be understood as a proxy to report to the Danish Gambling Authority.

The Standard Records is a set of XML schema definition (XSD) files that describe how the gaming data has be reported to the Danish Gambling Authority.

While the DDI API undergoes changes very infrequently, it is essential to note that adding new fields to the response message is considered a backward-compatible change. Therefore, your implementation must be accommodating of unknown fields in responses. This applies to all API endpoints.

Data submission is discussed in detail in section Sending data to DDI. This section only summarises the API endpoint.

Data has to be sent to DDI via POST requests. The data has to be either in XML or JSON formats and has to conform to corresponding XSD schema definition or JSON schema. And the data has to be sent differently for payloads larger than 1 MB

The attributes such as payloadType, gameCategory, etc are described in section API attributes. The actual sent payload and the validation is discussed in chapter Schemas.

Handling errors id described in detail in section Error handling.

Errors in data submission are handled differently in DDI for different errors. For instance requests with invalid payload or payload not confirming to the XSD schema or JSON schema will be rejected immediately with non-200 HTTP response. However certain errors such as logical errors in the payload are not rejected immediately. That is DDI will return a 200 response as the request may pass initial validation. All the requests passing initial validation are validated in detail within several minutes. If DDI encounters a logic error in the detailed validation it will create an error in Error Bucket. Supplier is obliged to check Error Bucket once every minute.

Error Bucket is a GET request to DDI which returns a list of errors. It can be used to retrieve all errors or only errors that were created after a certain error.

To retrieve all errors pass an empty in errorId parameter. However, only first 1000 errors will be fetched. So if there are more than 1000 pass the last error id in errorId as a parameter to receive next errors as described below.

errorId can be set to a specific error id. Then DDI will return all the errors that were created after specified errorId. But again no more than 1000 errors will be returned. To get more errors pass the last received error id to get a next errors section.

For instance setting errorId to last received error id will return a list of all new errors that might have been created.

Errors can be updated with ticket-id, proposed resolution via the API using the following API call: ./SAFE/errors/update/{supplier}/{errorId}

Optional query parameters:

Request:

Response:

As it will be discussed in detail in section Data submission the data sent to DDI has to conform to either XSD schema definition or JSON schema definition depending on the format of data being sent.

A zip file containing all schemas, both xml and json is available for download.

Every Danske Spil gaming data supplier has a unique supplier which has to be a part of data submission and error fetching endpoints. The supplier is constant and does not change over time. Danske Spil will issue a supplier during onboarding process.

Denotes the type of payload being sent to the data submission endpoints. Can either be xml or json.

If payloadType is set to xml then the submitted payload has to be in XML format. And if it is set to json then the payload has to be in JSON format. This is valid both when submitting small and large files. However when submitting large files the body of the request will contain only the reference to the referenced file in JSON format, also for the XML files. See section Large files for information on large file submission.

Indicates which game category is being used. Can either be monopol or other. Danske Spil will inform which game category to specify. In short monopol denotes that the gaming data relates to the monopoly games that only Danske Spil is licensed to issue. Whilst game category other has to be used for all other gaming data.

Defines which type of gaming data is being sent. This could be for example FastOddsSlutStrukturType or EndOfDayRapportStrukturType. Note that the same game type is be different for different payloadType. For xml payloadType the gameType will be in Danish, as it follows more-less directly the Standard Records. For json payloadType the gameType will be in English.

As mentioned above gameType follow data structures defined by the Standard Records (see section Standard Records). Thus it is a good idea to check DGA Standard Records documentation regarding game type of the gaming data being sent.

A list of possible game types along with a reference to DGA documentation can be found in section Available schemas.

SequenceId was a feature intended to help detect missing transactions, but it was never implemented and never will be. For backwards compatability though it is still part of the API, and it’s value should just be hardcoded to 1-1.

In the context of the DDI, a transaction refers to a gaming data payload accompanied by various attributes, such as SupplierId, GameType, TransactionId and others. A key part of each transaction is the TransactionId, which uniquely identifies the transaction sent to the DDI. Every new transaction must have a distinct TransactionId to ensure it is recognized as unique by the DDI.

If the same TransactionId is reused for multiple transactions, the system will reject it.

However if a transaction isn’t sent successfully for various reasons, and the sending system attempts to send it again, with exactly the same content, then it should not be assigned a new TransactionId

transactionId has a special format and consists of three sub-attributes: verticalId, timestamp and uid.

verticalId and timestamp are valuable attributes that ease troubleshooting issues with the gaming data

errorId is a unique error id that identifies an error from the Error Bucket. errorId is generated by the DDI.

When the DDI encounters an error while processing submitted game data it creates an error with a unique errorId. errorId can be used to retrieve list of errors from Error Bucket. See further information in section Retrieving errors.

errorId is a time-based UUID (UUID Version 1), for example c6537392-68f8-11e6-8b77-86f30ca893d3.

The environments are described in section Environments and API keys. The Host part of http requests will be omitted in the following examples.

The request path to DDI contains attributes that describe the payload being sent. The path and query parameters of the request contains information on type of payload (XML or JSON), supplier information, type of structure being submitted, additional flags or attributes in query parameters.

The request parameters are described in section API attributes. They will be discussed in more detail later on.

Integration to DDI is different for smaller and larger payloads.

DDI refers to smaller payloads as small files which cannot exceed 1 MB . Larger payloads are referred as large files which are above 1 MB

The difference between small files and large files is how the payload is being sent to DDI. All the other request attributes are nearly the same.

This section contains several examples of small files submission.

Connection to the SFTP server is configured separately for each environment.

To connect to a SFTP server a supplier has to generate private - public key pair and send the public key to Danske Spil. Danske Spil issues a username and sets up the connection. All Town environments share the same Large file key

The generated public SSH key has to be in OpenSSH format.

A step by step connection guide for one environment:

The SAFE2 SFTP server will be regularly updated to follow best practices regarding accepted cryptographic algorithms (message authentication codes (MACs), key exchanges (KEXs), and cipher suites).

As of January 2025, we use the policy described in AWS TransferSecurityPolicy-2024-01.

It is important that you keep your large file sending software updated to support best practices.

To make testing if new cipher suites are compatible with your client, we recommend that you add a feature to you reporting application that lets you do a simple connect check against any host (without doing any authentication). Then you can from your production environment verify against the SAFE2 test environment (where new ciphers will be applied first).

Initially upon the data submission the DDI will check only the request attributes and verify that the referenced file in the large file pointer actually exists. If no issues are found the DDI will then return 200. However, the actual payload validation happens within several minutes. Thus even though large file submission returns 200, it does not mean that the data submission was successful.

Same as with the small files, the large files have to conform to the corresponding XSD or JSON schemas that were defined in payloadType and gameType attributes in the request.

If the DDI encounters an error while processing a large file it will create an error in the Error Bucket. As was mentioned above the processing of large files is not immediate and may take several minutes. A game data supplier is obliged to check Error Bucket once a minute for new errors. See further information in section Error handling.

If a Standard record structure contains an array, it is recommended to bundle the data.

The DGA advices that purchases of the same type of game and draw should be bundled.

eg. instead of sending each game purchase as a transaction structure containing 1 purchase, the game purchases for a short period of time should be bundled, and send in the same transaction structure. So a transaction structure would contain more than 1 purchase.

The maximum period of bundling would/could be set to 1 minute with a limit of 100 purchases.

All dates/times/timestamps in the Standard Records structures must be reported in UTC.

Hence it is important that the EndOfDay calculation performed in the GameEngine is also calculated using UTC time, please see Transaction Reporting Isolation

When you send data in XML format, the SAFE2 system will replace the element SpilFilIdentifikation with the transactionId from the request URL, before validating the schema. So even though the schema mandates it, you are not required to fill in the SpilFilIdentifikation element.

Similar goes for the SpilFilErstatningIdentifikation element (used when sending replacements, see Replacement), which will automatically be added with the value of the resend URL parameter (if you send the SpilFilErstatningIdentifikation element, its contents will be replaced instead of being added).

Any leading or trailing whitespace within XML elements or JSON values is trimmed during processing before being sent to the DGA system.

For example, consider the following snippet, which illustrates how whitespaces are trimmed. Please note that since the DGA system only accepts XML-formatted data, any JSON data is automatically translated to XML.

During the onboarding phase Danske Spil guides suppliers through the DDI integration. And Danske Spil will inform how exactly the gaming data should be reported and which view schemas have to be used.

Once view schemas are known, it is a good idea to look explore the referenced class and type schemas to get a better understanding on how the data should be reported.

However, nearly always in addition to the reported gaming data a supplier has to report end-of-day and sometimes end-of-game structures. These structures summarize the gaming data and transactions sent for the whole day or for the whole game. End-of-day and end-of-game schemas exist both for xml and json payloadType, and both for other and monopol game categories. It is a good idea to get familiarized with these schemas as well.

The list of all available schemas is given in Available schemas.

Schemas are not changed often. Hence accessing schemas on different environments (see section Environments and API keys) will most likely have the same results. However, once DGA updates the XSD schemas, Danske Spil has to develop JSON schema changes as well. And then Danske Spil publishes the new XSD and JSON schemas in the DDI. First the schemas are published to Test environment, then to UAT and then to Production. Hence there might be period when different environments have a difference in schemas.

It is important to point out that the DDI respects the schemas that are published in a given environment. That is the DDI will perform the payload validation according to the version of the schemas that is published in the given environment.

This means that the DDI has receive a request and there is no immediate validation error. However this does not mean that there are no error in the submitted request. As mentioned in sections Sending data to DDI and Large files it can take up to several minutes to fully process the request. That is the in-deep validation and processing of the submitted data does not happen immediately.

After the in-deep validation and processing, the DDI may reject the request. This can be for instance related to the logic error in the transaction. In this case the DDI will create an error in the Error Bucket. The supplier is required to check the Error Bucket every minute and handle new errors. See more on the error handling in section Error handling.

This means that the DDI has rejected the submitted transaction immediately. No error will be created in the Error Bucket. The supplier has to correct the request and send it again.

As was mentioned above, the response from the DDI always include a further clarification on the error in the body of the response.

This means that an unexpected error occurred in the DDI while processing the request. The DDI does not save the sent transaction and the transaction has to be resent.

Upon receiving 500 HTTP response the supplier has to attempt sending the transaction again with one second delay between the second retry. And then doubling the delay for every next request if 500 HTTP response is returned. In total the supplier should make 10 attempts.

If the DDI still responds 500 after the last retry, the supplier has to create a ticket to Danske Spil (see section Contact Information). Obviously it is enough with one single ticket when multiple transactions are failing. No need to create a separate ticket for every failed transaction.

The failed transactions should not be resent until Danske Spil resolves the issue.

The following requirements for reporting frequency applies to a normal data flow, where no errors have been identified during the Data Validation. If errors have been identified in the data, the requirements stated in section Error handling must be followed.

This section contains details for the specific game type reporting. Sections Tests, Errors, Tickets apply to all games.

When reporting transactions, each transaction is stored and delivered to the DDI. The End of Day report should be calculated in the supplier Backend Datastore. As a supplier, you can not sum upon transactions passing through the DDI, since that will always match. You need to calculate End of Day in the Backend Datastore to take care of any unreported transactions.

The process for error handling is as follows:

A complete list of error that can be returned by the DDI is available in table Error Definitions.

Errors that will be caught by the API (step 2A in Process for error handling above) will result in rejection of the sent data and an error response from the API.

Rejection implies that the data, the {transactionId}, and the {sequenceId} have not reached Danske Spil. Therefore, the data message must be resent in a corrected state, but the same {transactionId} and {sequenceId} can be used.

The error response from the API includes errorMessage, errorType, and stackTrace in a json object (example below). The json object will be found in the body of the API response.

The game supplier can receive various error messages from the error queue depending on the type of error that has occurred.

Errors which will be caught by the Advanced Controls (step 3B in Process for error handling above) will result in an entry in the ErrorBucket.

The ErrorBucket should be pulled by the game supplier in defined intervals. [api-resources-2] is used for pulling the ErrorBucket (see section API resources).

Error messages from the ErrorBucket are returned to the game supplier in a json object. The below example contains a single error message

All fields marked with Optional can be omitted from an error message.

If a field is not relevant, or there is no information to show, it will be marked with Null.

E.g. any Missing SequenceId error will have the fields {transactionId} + {sequenceId} set to Null, as these fields are not relevant for the Missing SequenceId error.

Errors are grouped into error categories:

The severity of the error determines if the message was accepted or rejected.

Complete list of errors defined by the system.

When a game supplier encounters a problem, which they cannot solve themselves, or they pull an error from the ErrorBucket, they should inform DS operations. Contact should be through the agreed channels, which can be ticket system (e.g. JIRA), email, or similar.

The game supplier should send the following information to DS operations (minimum requirements):

It is important that the Game Supplier is as detailed as possible when explaining the issue, so that the error is identified and fixed effectively.

When the issue progresses in the ticket system, the game supplier should keep DS informed.

When a game supplier needs to correct data that has been sent to DDI, the resend parameter must be used. There are three different categories for resending data:

The type of structure being sent determines which category the resend falls into (see below). Valid values for the resend parameter are:

As a supplier, you need to monitor the error bucket to discover trends in errors. Should you not understand the error message in the trending error or disagree that this is an error, please create a jira ticket to Team Safe.

New versions will be distributed when available to listed contact persons. To ensure inclusion on the distribution list please contact operations@danskespil.dk.

Changes to the documentation can be send to operations@danskespil.dk. Please provide the information requested in the below table.

Submitter of change request

Company: Name: E-mail:

The {supplier} must be agreed upon with Danske Spil to ensure uniqueness. Please contact operations@danskespil.dk to obtain a {supplier}.

The {verticalId} must be agreed upon with Danske Spil to ensure uniqueness. Please contact operations@danskespil.dk to obtain a {verticalId}.

The API-Key must be designed by Danske Spil to ensure uniqueness. Please contact operations@danskespil.dk to obtain a API-Key.

When clicking the DGA link a page refresh can be needed to jump to the pdf page.