Changes to DataSet v1 → v2 (non-breaking) – OnlineFundraising

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"
        }
    }
}

How may we help?

DataSet API

Introduction