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). |
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. |
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 |