DataSet API

Introduction

Immediately after a form is submitted, a DataSet is created containing the submitted form request and the form’s configuration at the time of submission. If the form submission is transactional in nature and the payment session is completed, the DataSet's “jsonElement” is updated with a “paymentSessionResult” object containing all relevant payment entity guids.

Important: Before using the DataSet API, please make sure that you have a fundmental understanding of DataSets.

Properties

Name	Type	Description
dataSetGuid	STRING	Unique GUID
merchantId	STRING	Readable ID of the merchant
createdTs	TIMESTAMP	Timestamp of DataSet creation
updatedTs	TIMESTAMP	Timestamp of DataSet update
jsonElement	OBJECT	JSON string containing several objects. Please see contents below.

Endpoints

GET /dataSets?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}

Get a list of DataSets at a given size, offset and date limitation.

Response

HTTP	Description
200	OK

HTTP 200 Example

{
  "pageNumber": {
    x
  },
  "pageSize": {
    y
  },
  "startDate": {
    yyyy-mm-dd
  },
  "endDate": {
    yyyy-mm-dd
  },
  "list": [
    {
      "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "...": "...",
      
    },
    {
      "dataSetGuid": "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx",
      "...": "...",
      
    }
  ]
}

GET /dataSet/{guid}

Get a single DataSet.

Response

HTTP	Description
200	OK
404	Data Set was not found

HTTP 200 Example

{
  "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "merchantId": "your-organisation",
  "createdTs": "2019-12-31 15:59:59 +0100",
  "updatedTs": "2019-12-31 15:59:59 +0100",
  "jsonElement": "Please see example"
}

POST /dataSet

Insert a single DataSet.

Please note: we do not validate the posted data or structure. We simply store data as it is received for optional later use.

If you are engaging our Payment Session Handler directly, you might want to store data differently. However we prefer two objects (example below):

formResult, an object containing the keys and values of a posted form, and a
formFields, an array containing additional properties for inputType, label, name, value, options and attr (attributes).
These are useful when building a user interface or a receipt with human readable content.

Request

We recommend the following is provided in the request body:

{
  "formResult": {
    "name": "",
    "email": "",
    "...": "..."
  },
  "formFields": [
    {
      "inputType": "text",
      "label": "Name",
      "name": "name",
      "value": "John Doe",
      "options": "",
      "attr": "",
      
    },
    {
      "inputType": "email",
      "label": "Email",
      "name": "email",
      "value": "john.doe@yourdomain.tld",
      "options": "",
      "attr": "",
      
    },
    "...": "..."
  ],
  "dataSetVendor": "My Fundraising Application"
}

Response

HTTP	Description
201	Created
400	Something's wrong with request body.

HTTP 201 Example

{
  "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "...": "..."
}

PUT /dataSet/{guid}

Replace a single DataSet.

Request

The following must be provided as the request body:

{
  "formResult": {
    "name": "",
    "email": "",
    "...": "..."
  },
  "formFields": [
    {
      "inputType": "text",
      "label": "Name",
      "name": "name",
      "value": "John Doe",
      "options": "",
      "attr": "",
      
    },
    {
      "inputType": "email",
      "label": "Email",
      "name": "email",
      "value": "john.doe@yourdomain.tld",
      "options": "",
      "attr": "",
      
    },
    "...": "..."
  ]
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	DataSet was not found

HTTP 200 Example

{
  "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "...": "..."
}

DataSet and changes

Depending on the type of action either a DataSet or a Changelog is added to the entity.

Action	Entity	Handling
Upgrade	Agreement amount or frequency	Changelog with optional MetaData
Upgrade	AddOn (entity)	DataSet with optional MetaData
Renewal	PaymentMethod	DataSet with optional MetaData
SignUp	Payment	DataSet with optional MetaData
SignUp	Subscription	DataSet with optional MetaData
SignUp	Subscription m. OneOff	DataSet with optional MetaData
SignUp	DataSet	DataSet with optional MetaData
Refund	Payment	Changelog
Cancel	Subscription	Changelog
Hold	Subscription	Changelog
Restart	Subscription	Changelog
Anonymise	Contact	Changelog
Archive	Contact	Changelog
Merge	Contact	Changelog

Contents of the DataSet’s jsonElement

Property	Mandatory	Description
formResult	No	An object containing the keys and values of a posted form.
formFields	No	An array of objects containing field properties for inputType, label, name, value, options and attr (attributes). These are useful when building a user interface or a receipt with human readable content.
paymentSessionResult	No	An object containing relevant payment entity guids.
dataSetType	No	A string usually populated by either “onboarding-form” or “onboarding-app”, but an integrator may assign something else.
dataSetTransactional	No	Boolean, indicating if the form submission is transactional in nature, as forms may also be used for petitions and other kinds of data collection.
dataSetThirdParty	No	Boolean, indicating if the form submission’s payment method is third party to OnlineFundraising, and therefore will not be processed by the payment engine. This is useful for organisations collecting information for Betalingsservice, but maintaining subscriptions and payments elsewhere.
dataSetVendor	No	A string presenting the name of an integrator's application or company, visible to the organisation in OnlineFundraising.

Please note you may find additional objects in relation to i.e. Onboarding or SMS Inbound. These are predominately meant for internal use and logging, and should be disregarded.

This is an example of a jsonElement:

{
  "dataSetType": "onboarding-form",
  "dataSetTransactional": true,
  "dataSetThirdParty": false,
  "dataSetVendor": "My Fundraising Application",
  "formResult": {
    "name": "",
    "email": "",
    "...": "..."
  },
  "formFields": [
    {
      "inputType": "text",
      "label": "Name",
      "name": "name",
      "value": "John Doe",
      "options": "",
      "attr": "",
      
    },
    {
      "inputType": "email",
      "label": "Email",
      "name": "email",
      "value": "john.doe@yourdomain.tld",
      "options": "",
      "attr": "",
      
    },
    "...": "..."
  ],
  "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"
  }
}

Besides fields configured in our form builder each DataSet can contain the following list of additional fields, should they be populated:

Name	Key	Description
UTM Source	utm_source	Useful when tracking source of traffic
UTM Medium	utm_medium	Useful when tracking source of traffic
UTM Campaign	utm_campaign	Useful when tracking source of traffic
UTM Content	utm_content	Useful when tracking source of traffic
UTM Term	utm_term	Useful when tracking source of traffic
Embed URL	embed_url	The URL containing the embedded form
Referer URL	referer_url	The URL leading to the embedded form, such as “https://l.facebook.com/”
Form width	width	The width of the embedded form in pixels, used to apply mobile styling
Device width	device	The width of the device in pixels, used to negate mobile styling based on device
OS	os	Operating System, such as: “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36"
IP	ip	IP address
Google Analytics Client ID	_ga	The Google Analytics Client ID received from URL with embedded form

How may we help?

Introduction

Properties

Endpoints

GET /dataSets?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}

Response

GET /dataSet/{guid}

Response

POST /dataSet

Request

Response

PUT /dataSet/{guid}

Request

Response

DataSet and changes

Contents of the DataSet’s jsonElement