DataSet API

DataSet API

API Documentation

Senest redigeret:

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 fundamental understanding of DataSets.

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": 1,
  "pageSize": 50,
  "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": "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",
    "sourceGuid": "101",
    "isTransactional": true,
    "isThirdParty": false,
    "sensitive_data": [
        "middleName",
        "phone2"
    ],
    "jsonElement": {
        "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"
        }
    }
}

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:

{
    "vendor": "my-vendor-name",
    "sensitive_data": [
        "middleName",
        "phone2"
    ],
    "jsonElement": {
        "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"
        }
    }
}

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:

{
    "jsonElement": {
        "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"
        }
    }
}

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",
  "...": "..."
}

Schema

The table below shows the top level of a DataSet. Please refer to DataSet Schema for detailed documentation.

Property

Format and Description

dataSetGuid

string<uuid>

Unique GUID

merchantId

string

Readable ID of the merchant

createdTs

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

Timestamp of DataSet creation

updatedTs

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

Timestamp of DataSet update

jsonElement

object

JSON string containing several objects.

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