How may we help?

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