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 |