DataSet API

Changes to DataSet v1 → v2 (non-breaking)

API Documentation

Senest redigeret:

Introduction

This article describes the changes for DataSet from version 1 (v1) to version 2 (v2). DataSet v2 was rolled out in 2023 Q1 - see here for release notes.

Important: This release is non-breaking.

Changes to DataSet

The table below describes the properties of the DataSet entity, and it highlights which version they originate from as well. See further down for examples.

Preoperty

Version

Mandatory

Format and description

dataSetGuid

V1

SYSTEM

string<uuid>
Unique GUID.

merchantId

V1

SYSTEM

string
Readable ID of the merchant.

createdTs

V1

SYSTEM

string<yyyy-MM-dd HH:mm:ss zzzz>
Timestamp of DataSet creation.

updatedTs

V1

SYSTEM

string<yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of DataSet update.

anonymizedTs

V2

SYSTEM

string<yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of DataSet anonymisation.This is a new field.

jsonElement

V1

TRUE

object

JSON string containing several objects: formResult, formFields, and paymentSessionResult.

sensitiveData

V2

FALSE

array<string>

Definition of custom sensitive data fields eligible for anonymisation. This is a new field.

Examples: "middleName","phone2","sexuality"

isTransactional

V2

FALSE

boolean

Defines whether the data is transactional or not. Replaces jsonElement.dataSetTransactional.

Default value: false

isThirdParty

V2

FALSE

boolean

Defines whether the data is managed by PaymentEngine or not. Replaces jsonElement.dataSetThirdParty.

Default value: false

vendor

V2

FALSE

string

Defines the name of the integrator or their solution. Replaces jsonElement.dataSetVendor.

sourceType (See details)

V2

FALSE

string

Defines the source of the DataSet. Replaces jsonElement.dataSetType

Values: "form", "onboarding", "sms"

sourceGuid

V2

FALSE

string

Defines the specific path of the sourceType, such as the Form Id, Onboarding Session or SMS Keyword. This is a new field.

sourceType

The property sourceType is populated based on the presence jsonElements properties. 

Preoperty

Version

Format and description

jsonElement.session

V1

string
Is translated to sourceType = "onboarding".

jsonElement.smsMo

V1

string
Is translated to sourceType = "sms".

jsonElement.form_id

V1

string
Is translated to sourceType = "form".

Deprecated Fields

The table below describes fields that have been deprected (but not removed) in DataSet v2.

Preoperty

Version

Status

Format and description

jsonElement.dataSetType

V1

Deprecated

string
Replaced by sourceType.

Values: "onboarding-form", "sms", "form"

jsonElement.dataSetTransactional

V1

Deprecated

boolean
Replaced by isTransactional.

jsonElement.dataSetThirdParty

V1

Deprecated

boolean
Replaced by isThirdParty.

jsonElement.dataSetVendor

V1

Deprecated

string
Replaced by vendor.

Examples

Example - DataSet v1 (Form)

{
  "dataSetGuid": "4e6c4a00-314f-4370-b6c5-ceae74eaa6ba",
  "merchantId": "onlinefundraising-test",
  "createdTs": "2022-07-12 09:00:14 +0200",
  "updatedTs": "2022-07-12 09:00:39 +0200",
  "jsonElement": {
      "dataSetType": "form",
      "dataSetTransactional": true,
      "dataSetThirdParty": false,
      "dataSetVendor": "My OnlineFundraising Application",
      "formResult": {
        "name": "",
        "email": "",
        "...": "..."
      },
      "formFields": [
        {
          "inputType": "text",
          "label": "Name",
          "name": "name",
          "value": "John Doe"
        },
        {
          "inputType": "email",
          "label": "Email",
          "name": "email",
          "value": "john.doe@yourdomain.tld"
        },
        {
"...": "..."
} ], "paymentSessionResult": { "postProcessedTs": "2019-12-31 15:59:59 +0100", "postProcessingErrorTs": "2019-12-31 15:59:59 +0100", "postProcessingErrorDescription": "", "contactGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "paymentMethodGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "agreementGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "subscriptionGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "paymentGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx" } } }

Example - DataSet v2 (Form)

{
    "dataSetGuid": "4e6c4a00-314f-4370-b6c5-xxxxxxxxxxxx",
    "merchantId": "onlinefundraising",
    "createdTs": "2022-07-12 09:00:14 +0200",
    "updatedTs": "2022-07-12 09:00:39 +0200",
    "sourceType": "form", // New field
    "sourceGuid": "101", // New field
    "isTransactional": true, // New field
    "isThirdParty": false, // New field
    "sensitive_data": [ // New field
        "middleName",
        "phone2"
    ],
    "jsonElement": {
      "dataSetType": "form", // Deprecated
      "dataSetTransactional": true, // Deprecated
      "dataSetThirdParty": false, // Deprecated
        "formResult": {
            "name": "John Doe",
            "email": "john.doe@yourdomain.tld",
            "...": "..."
        },
        "formFields": [
            {
                "inputType": "text",
                "label": "Name",
                "name": "name",
                "value": "John Doe"
            },
            {
                "inputType": "email",
                "label": "Email",
                "name": "email",
                "value": "john.doe@yourdomain.tld"
            },
            {
                "...": "..."
            }
        ],
        "paymentSessionResult": {
            "postProcessedTs": "2019-12-31 15:59:59 +0100",
            "postProcessingErrorTs": "2019-12-31 15:59:59 +0100",
            "postProcessingErrorDescription": "",
            "contactGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
            "paymentMethodGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
            "agreementGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
            "subscriptionGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
            "paymentGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
        }
    }
}