DataSet API

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.

Properties

Name

Type

Description

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.

 

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

HTTP

Description

200

OK

HTTP 200 Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { "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

HTTP

Description

200

OK

404

Data Set was not found

HTTP 200 Example

1 2 3 4 5 6 7 { "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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 { "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

HTTP

Description

201

Created

400

Something's wrong with request body.

HTTP 201 Example

1 2 3 4 { "dataSetGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx", "..." : "..." }

 

PUT /dataSet/{guid}

Replace a single DataSet.

Request

The following must be provided as the request body:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { "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

HTTP

Description

200

OK

400

Something's wrong with request body.

404

DataSet was not found

HTTP 200 Example

1 2 3 4 { "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

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

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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 { "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

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