Following are descriptions of all available entities in OnlineFundraising v4.0 onwards and their properties, however you may prefer starting with our guide for a simple integration.

1.0 Contact

A Contact represents the individual with whom we are dealing with and can either be a person or a business.

Properties

Name	Type	Mandatory	Example	Description
contactGuid	STRING	-		Unique GUID
merchantId	STRING	-		Readable ID of the merchant
name	STRING	NO	Fundraisingbureauet ApS	Full name of Contact
birthDate	DATE	NO		Birthday of Contact (YYYY-MM-DD)
nationalId	STRING	NO		National ID (i.e. CPR in Denmark provided without dashes)
address	STRING	NO	Store Kongensgade 59B, 3.	Address
address2	STRING	NO		Address line 2
postCode	STRING	NO	1264	Postcode
city	STRING	NO	København K	City
countryCode	STRING	NO	DK	ISO formatted Country Code (wiki)
msisdn	STRING	NO	4535294855	Phone with Country Code (wiki on Country Code) with 1-3 digits reserved for country code without prefixes, such as 00 (wiki on MSISDN).
email	STRING	NO	support@onlinefundraising.dk	Email of the Contact
firstName	STRING	NO		First name
lastName	STRING	NO		Last name
companyName	STRING	NO	Fundraisingbureauet ApS	Company name
businessCode	STRING	NO	37273457	Business Code (i.e. VAT, CVR in Denmark)
contactType	STRING	NO	individual, business	Type of Contact. Please note the value is not restricted to the examples given, however our form field will use these.
createdTs	TIMESTAMP	-		Timestamp of Contact creation
updatedTs	TIMESTAMP	-		Timestamp of last update
archivedTs	TIMESTAMP	-		Timestamp of archivation after which the Contact is hidden from queries.
externalId	STRING	NO		An external ID
externalLink	STRING	NO		An external URL to e.g. CRM
originTs	TIMESTAMP	NO		Timestamp of origin, useful when importing data
mergeTargetGuid	STRING	-		A GUID of that contact that this has been merged into.
mergeTs	TIMESTAMP	-		Timestamp of the merge operation.

The contactType property

As stated above the contactType property is not restricted to either "individual" or "business", however please note our form field will use these and show/hide the relevant fields upon selection.

	individual	business
name	v	x
firstName	v	v
lastName	v	v
companyName	x	v
nationalId	v	x
businessCode	x	v
address	v	v
postCode	v	v
city	v	v
countryCode	v	v
msisdn	v	v

GET /contacts?pageNumber={x}&pageSize={y}&archived=false|true

Get a list of Contacts at a given size by a given offset. Use "archived" (defaults to false) to focus your query. All parameters are optional.

Response

HTTP	Description
200	OK

HTTP 200 Example

{
	"pageNumber" : {x},
	"pageSize" : {y},
	"list" : [
		{
			"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		},
		{
			"contactGuid" : "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx",
			"..." : "...",
		}
	]
}

GET /contacts?search={email|msisdn}

Get an array of Contacts by a given search string matching either email or msisdn (phone).

Response

HTTP	Description
200	OK

HTTP 200 Example

[
	{
		"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"contactGuid" : "c0f7cf91-1175-4283-9369-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /contact/{guid}

Get a single Contact.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

{
	"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"merchantId" : "your-organisation",
	"name" : "Jens Jensen",
	"birthDate" : "2005-07-10",
	"nationalId" : "1007059995",
	"address" : "Store Kongensgade 59B",
	"address2" : "",
	"postCode" : "1264",
	"city" : "København K",
	"countryCode" : "DK",
	"msisdn" : "4535294855",
	"email" : "",
	"firstName" : "Jens",
	"lastName" : "Jensen",
	"companyName" : "",
	"businessCode" : "",
	"createdTs" : "2019-12-31 15:59:59 +0100",
	"updatedTs" : "",
	"archivedTs" : "",
	"externalId" : "",
	"externalLink" : ""
}

POST /contact

Insert a single Contact.

Please note our API accepts the given properties as is, and will not validate e.g. email, msisdn, nationalId, businessCode, address, birthDate, (full)name against given firstName and lastName.

Request

The following may be provided as the request body:

{
	"name" : "Jens Jensen",
	"birthDate" : "2005-07-10",
	"nationalId" : "1007059995",
	"address" : "Store Kongensgade 59B",
	"address2" : "",
	"postCode" : "1264",
	"city" : "København K",
	"countryCode" : "DK",
	"msisdn" : "4535294855",
	"email" : "",
	"firstName" : "Jens",
	"lastName" : "Jensen",
	"companyName" : "",
	"businessCode" : "",
	"externalId" : "",
	"externalLink" : ""
}

Response

HTTP	Description
201	Created
400	Something's wrong with request body.

HTTP 201 Example

{
    "contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "..." : "..."
}

PUT /contact/{guid}

Replace a single Contact.

Request

The following may be provided as the request body:

{
	"name" : "Jens Jensen",
	"birthDate" : "2005-07-10",
	"nationalId" : "1007059995",
	"address" : "Store Kongensgade 59B",
	"address2" : "",
	"postCode" : "1264",
	"city" : "København K",
	"countryCode" : "DK",
	"msisdn" : "4535294855",
	"email" : "",
	"firstName" : "Jens",
	"lastName" : "Jensen",
	"companyName" : "",
	"businessCode" : "",
	"externalId" : "",
	"externalLink" : ""
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Contact was not found

HTTP 200 Example

{
    "contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "..." : "..."
}

PATCH /contact/{guid}

Update a single Contact using add, replace or remove operations.

Request

The following must be provided as the request body:

[
	{
		"op" : "add|replace|remove",
		"path" : "/address",
		"value" : "Store Kongensgade 59A"
	}
]

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Contact was not found

POST /contact/{guid}/Anonymise

Anonymising a Contact will delete all properties revealing personal information, and then mark it archived to hide it from queries. This means the entity will as such be kept as it ties Subscriptions, Payment Methods and Payments together, which might be relevant later for accounting purposes.

Response

HTTP	Description
200	OK
400	Contact cannot be archived, most likely due to active Subscriptions
404	Contact was not found

POST /contact/{guid}/Archive

Archiving a Contact will hide it from queries.

Response

HTTP	Description
200	OK
400	Contact cannot be archived, most likely due to active Subscriptions
404	Contact was not found

POST /contact/{guid}/Merge

Merge two Contacts: a duplicate Contact defined in the endpoint URL and a target Contact defined in the request body.

A callback will be sent on a successful merge for the duplicate Contact being merged. Nothing is sent for the target Contact.
After a successful merge, the property mergeTargetGuid is set on the archived duplicate Contact.

Request

The following must be provided as the request body:

{
	"mergeTargetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body
404	Either the duplicate or target guid was not found

GET /contact/{guid}/paymentMethods

Get a list of Payment Methods for a single Contact.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

[
	{
		"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"paymentMethodGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"paymentMethodGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /contact/{guid}/agreements

Get a list of Agreements for a single Contact.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

[
	{
		"agreementGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"agreementGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /contact/{guid}/addOns

Get a list of AddOns for a single Contact.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

[
	{
		"addOnGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"addOnGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /contact/{guid}/subscriptions

Get a list of Subscriptions for a single Contact.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

[
	{
		"subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /contact/{guid}/payments

Get a list of Payments for a single Contact at a given size by a given offset.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

[
	{
		"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /contact/{guid}/receipts

Get a list of /wiki/spaces/OFpublic/pages/327891 for a single Contact at a given size by a given offset.

Response

HTTP	Description
200	OK
404	Contact was not found

HTTP 200 Example

[
	{
		"receiptGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"receiptGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /contact/{guid}/log?limit={limit}

Get a list of changes to an Contact.

Response

HTTP	Description
200	OK

HTTP 200 Example

[
  {
    "changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx",
    "createdTs": "2021-01-01 00:00:00 +0100",
    "entityType": "Contact",
    "entityGuid": "9a7c3665-5be0-4a5c-9641-xxxxxxxxxxxx",
    "changeTs": "2021-01-01 00:00:00 +0100",
    "oldEntityJson": "{ .. }",
    "changeDescription": "Updated by PUT request",
    "requester": "",
    "systemRequest": false,
    "changes": [
      {
        "newValue": "John Arne",
        "oldValue": "John",
        "fieldName": "name"
      }
    ]
  }
]

2.0 Agreement

An Agreement represents a recurring donation, membership, service, or a recurring purchase of a product, and so answers what is being paid for, for how much, when and how often.

Properties

Name	Type	Mandatory	Default	Example	Description
agreementGuid	STRING(64)	-		a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID
createdTs	TIMESTAMP	-			Timestamp of Agreement creation
merchantId	STRING	-			Readable ID of the merchant
name	STRING(30)	YES			Name of Agreement
description	STRING(60)	NO			Invoice description
agreementType	STRING	YES		Personal / Shared	Agreements can either be Personal or Shared. Shared agreements are used by many Contacts, such as memberships with a certain frequency and amount, whereas personal agreements are unique to each individual Contact, such as a recurring donation of a specific frequency and amount.
contactGuid	STRING(64)	NO		a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	GUID of Contact
communicationCollectionGuid	STRING(64)	NO		a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	GUID of Communication Collection
defaultQuantity	INTEGER	NO	1		Default quantity
unit	STRING	YES		pcs	Unit
unitPrice	DOUBLE	YES		100.0	The price of a single unit
amount	DOUBLE	YES		100.0	Summarized amount excluding VAT
amountVat	DOUBLE	YES		25.0	Amount VAT
amountTotal	DOUBLE	YES		125.0	Total amount including VAT used when charging
taxDeductable	BOOLEAN	YES		true	Defines basis for tax deductibility
vatPercentage	DOUBLE	YES		25.0	VAT percentage
currencyCode	STRING	YES		DKK	ISO formatted Currency Code (wiki)
state	STRING	-			Please see list of Agreement States below.
paymentRequired	BOOLEAN	YES		true	Are Payments required for the Agreement's Subscriptions to be valid?
scheduleType	STRING	YES		Monthly	Please see list of Agreement Schedule Types below.
scheduleBaseTier	INTEGER	YES			The offset in relation to the chosen calendarUnit. Please see examples below.
scheduleFixedDay	INTEGER	YES		1-28	A fixed day of the chosen calendarUnit. Please note we do not accept the 29-31 of any month. Please see examples below.
scheduleEveryOther	INTEGER	YES			Please see description below. Skip every other due date.
scheduleCalendarUnit	STRING	NO	Month	Month	Calculate due date based on the chosen calendarUnit. Please see list of Schedule Calendar Units below.
scheduleSelectedSet	STRING	NO		"[1,2,3,4,5,6]"	Only calculate due dates when due date based on calendarUnit is in provided set of integers.
archivedTs	TIMESTAMP	-			Timestamp of archivation
externalId	STRING	NO			An external ID
originTs	TIMESTAMP	NO			Timestamp of origin, useful when importing data
purposeAccountingCode	STRING(32)	NO			Accounting Code defined by Merchant used to identify the receiving part of transactions
dataSetGuid	STRING(64)	NO		a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	A DataSet GUID containing metadata

GET /agreements?pageNumber={x}&pageSize={y}&state={z}

Get a list of Shared Agreements at a given size by a given offset and availability type. Use "state" (see list of states below) to focus your query. All parameters are optional.

Response

HTTP	Description
200	OK

HTTP 200 Example

{
	"pageNumber" : {x},
	"pageSize" : {y},
	"list" : [
		{
			"agreementGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		},
		{
			"agreementGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		}
	]
}

GET /agreement/{guid}

Get a single Agreement.

Response

HTTP	Description
200	OK
404	Agreement not found

HTTP 200 Example

{
	"agreementGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"createdTs" : "2019-01-01 00:00:00 +0100",
	"merchantId" : "your-organisation",
	"name" : "Youth Membership",
	"description" : "",
	"agreementType" : "Shared",
	"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"communicationCollectionGuid" : "",
	"defaultQuantity" : 1,
	"unit" : "pcs",
	"unitPrice" : 100.0,
	"amount" : 100.0,
	"amountVat" : 25.0,
	"amountTotal" : 125.0,
	"taxDeductable" : false,
	"vatPercentage" : 25.0,
	"currencyCode" : "DKK",
	"state" : "",
	"paymentRequired" : true,
	"scheduleType" : "Monthly",
	"scheduleBaseTier" : 1,
	"scheduleFixedDay" : 1,
	"scheduleEveryOther" : 1,
	"scheduleCalendarUnit" : "Month",
	"scheduleSelectedSet" : "[1,2,3,4,5,6]",
	"purposeAccountingCode" : "",
	"dataSetGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
}

POST /agreement

Insert a single Agreement.

Request

The following must be provided as the request body:

{
	"name" : "Youth Membership",
	"description" : "",
	"agreementType" : "Shared/Personal",
	"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"defaultQuantity" : 1,
	"unit" : "pcs",
	"unitPrice" : 100.0,
	"amount" : 100.0,
	"amountVat" : 25.0,
	"amountTotal" : 125.0,
	"taxDeductable" : false,
	"vatPercentage" : 25.0,
	"currencyCode" : "DKK",
	"paymentRequired" : true,
	"scheduleType" : "Monthly",
	"scheduleBaseTier" : 1,
	"scheduleFixedDay" : 1,
	"scheduleEveryOther" : 1,
	"scheduleCalendarUnit" : "Month",
	"scheduleSelectedSet" : "[1,2,3,4,5,6]",
	"purposeAccountingCode" : "",
	"dataSetGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
}

Response

HTTP	Description
201	Created
400	Something's wrong with request body.

HTTP 200 Example

{
    "agreementGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "..." : "..."
}

PUT /agreement/{guid}

Replace a single Agreement.

Request

The following must be provided as the request body:

{
	"name" : "Youth Membership",
	"description" : "",
	"agreementType" : "Shared/Personal",
	"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"defaultQuantity" : 1,
	"unit" : "pcs",
	"unitPrice" : 100.0,
	"amount" : 100.0,
	"amountVat" : 25.0,
	"amountTotal" : 125.0,
	"taxDeductable" : false,
	"vatPercentage" : 25.0,
	"currencyCode" : "DKK",
	"paymentRequired" : true,
	"scheduleType" : "Monthly",
	"scheduleBaseTier" : 1,
	"scheduleFixedDay" : 1,
	"scheduleEveryOther" : 1,
	"scheduleCalendarUnit" : "Month",
	"scheduleSelectedSet" : "[1,2,3,4,5,6]",
	"purposeAccountingCode" : "",
	"dataSetGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Agreement not found

HTTP 200 Example

{
    "agreementGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "..." : "..."
}

PATCH /agreement/{guid} PLANNED

Update a single Agreement.

Request

The following must be provided as the request body:

[
	{
		"op" : "replace",
		"path" : "/amount",
		"value" : 200.0
	}
]

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Agreement was not found

POST /agreement/{guid}/ChangeAmount

Change amount of a single Agreement.

Request

The following must be provided as the request body:

{
	"unitPrice": 100.0,
	"quantity": 1,
	"amount": 100.0,
	"amountVat": 25.0,
	"amountTotal": 125.0,
	"vatPercentage": 25.0
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Agreement was not found

POST /agreement/{guid}/ChangeFrequency

Change frequency of a single Agreement.

Request

The following must be provided as the request body:

{
	"scheduleType" : "Monthly",
	"scheduleBaseTier" : 1,
	"scheduleFixedDay" : 1,
	"scheduleEveryOther" : 1,
	"scheduleCalendarUnit" : "Month",
	"scheduleSelectedSet" : "[1,2,3,4,5,6]"
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Agreement was not found

POST /agreement/{guid}/Archive

Archives a single Agreement.

Response

HTTP	Description
200	OK
404	Agreement was not found

GET /agreement/{guid}/payments?pageNumber={x}&pageSize={y}

Get a list of Payments at a given size by a given offset.

Response

HTTP	Description
200	OK

HTTP 200 Example

{
	"pageNumber" : {x},
	"pageSize" : {y},
	"list" : [
		{
			"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		},
		{
			"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		}
	]
}

GET /agreement/{guid}/subscriptions?pageNumber={x}&pageSize={y}

Get a list of Agreements at a given size by a given offset.

Response

HTTP	Description
200	OK

HTTP 200 Example

{
	"pageNumber" : {x},
	"pageSize" : {y},
	"list" : [
		{
			"subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		},
		{
			"subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		}
	]
}

GET /agreement/{guid}/log?limit={limit}

Get a list of changes to an Agreement.

Response

HTTP	Description
200	OK

HTTP 200 Example

[
  {
    "changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx",
    "createdTs": "2021-01-01 00:00:00 +0100",
    "entityType": "Agreement",
    "entityGuid": "9a7c3665-5be0-4a5c-9641-xxxxxxxxxxxx",
    "changeTs": "2021-01-01 00:00:00 +0100",
    "oldEntityJson": "{ .. }",
    "changeDescription": "Updated by PUT request",
    "requester": "",
    "systemRequest": false,
    "changes": [
      {
        "newValue": "Membership",
        "oldValue": "Donation",
        "fieldName": "name"
      }
    ]
  }
]

Schedule Types

Following is a list of allowed schedule types:

scheduleType	Description
Manual	Payment occurs only when manually initiated
Custom	Uses provided baseTier, fixedDay, everyOther, calendarUnit and selectedSet to calculate next dueDate
Daily	Daily occurrence
Weekly	Weekly occurrence (~52 per year)
Monthly	Monthly occurrence (12 per year)
Quarterly	Quarterly occurrence (4 per year)
Halfyearly	Biannual occurrence (2 per year)
Yearly	Annual occurrence (1 per year)
MonthlyFirst	Monthly occurrence on the 1st of given month
QuarterlyFirst	Quarterly occurrence on the 1st of given month
HalfyearlyFirst	Biannual occurrence on the 1st of given month
YearlyFirst	Annual occurrence on the 1st of given month

Schedule Calendar Units

Following is a list of allowed schedule calendar units:

scheduleCalendarUnit	Description
Day	One day
Week	One week
Month	One month

Examples of schedules

All the following examples, assumes that the start date of the related subscription is the 1st of January.

Example 1 - A fixed day of every month

The following will calculate due dates the 7th of every month. When scheduleEveryOther is 1, scheduleBaseTier does not have any effect.

scheduleType: Monthly
scheduleBaseTier: 1
scheduleFixedDay: 7
scheduleEveryOther: 1
scheduleCalendarUnit: Month

Calculated dates are: 7/1, 7/2, 7/3, ...

Example 2 - A fixed day of every other month

The following will calculate due dates at the 14th of every other month, starting in February.

scheduleType: Custom
scheduleBaseTier: 2
scheduleFixedDay: 14
scheduleEveryOther: 2
scheduleCalendarUnit: Month

Calculated dates are: 14/2, 14/4, 14/6, ...

Example 3 - A fixed day in the beginning of every quarter

The following will calculate due dates the 10th of every quarter, starting in March.

scheduleType: Quarterly
scheduleBaseTier: 3
scheduleFixedDay: 10
scheduleEveryOther: 3
scheduleCalendarUnit: Month

Calculated dates are: 10/3, 10/6, 10/9, ...

Example 4 - A fixed day in the end of every year

The following will calculate due dates the 28th of every December.

scheduleType: Yearly
scheduleBaseTier: 12
scheduleFixedDay: 28
scheduleEveryOther: 12
scheduleCalendarUnit: Month

Calculated dates are: 28/12-2018, 28/12-2019, 28/12-2020, ...

Example 5 - The 2nd of a chosen set of months

The following will calculate due dates the 2nd of the selected months.

scheduleType: Custom
scheduleBaseTier: 1
scheduleFixedDay: 2
scheduleEveryOther: 1
scheduleCalendarUnit: Month
scheduleSelectedSet: 1, 4, 5, 11

Calculated dates are: 2/1, 2/4, 2/5, 2/11, ...

Example 6 - Every week, starting from the 1. of May 2020

The following will calculate due dates every week, start from the 1. of May 2020.

Since the 1. of May 2020 is a friday, scheduleFixedDay should be set to 5.

scheduleType: Weekly
scheduleBaseTier: 1
scheduleFixedDay: 5
scheduleEveryOther: 1
scheduleCalendarUnit: Week

Calculated dates are: 1/5-2020, 8/5-2020, 15/5-2020, 22/5-2020, 29/5-2020, ...

Agreement States

Following is a list of Agreement states:

State	Description
Available	Agreement is available for Subscriptions.
Archived	Agreement was archived and is hidden from queries.

3.0 AddOn

An Add On represents a single Add On on top of an Agreement in relation to a Subscription

Properties

Name	Type	Mandatory	Default	Example	Description
addOnGuid	STRING	-		a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID
merchantId	STRING	-			Readable ID of the merchant
createdTs	TIMESTAMP	-			Timestamp of AddOn creation
subscriptionGuid	STRING	YES		a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID of Subscription
contactGuid	STRING	YES		a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID of Contact
dataGuid	STRING	NO		a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID of DataSet holdning metaData
name	STRING	YES		Gift	Name of AddOn
description	STRING	NO			Invoice description
quantity	INTEGER	NO	1	1	Quantity
unit	STRING	YES		pcs	Unit
unitPrice	DOUBLE	YES		100.0	Unit price of a single AddOn
amount	DOUBLE	YES		100.0	Summarized amount excluding VAT
amountVat	DOUBLE	YES		0.0	Amount VAT
amountTotal	DOUBLE	YES		100.0	Total amount including VAT
vatPercentage	DOUBLE	YES		0.0	VAT percentage
taxDeductable	BOOLEAN	YES			Defines basis for tax deductibility
state	STRING	-			Please see list of AddOn States below
externalId	STRING	NO			An external ID
purposeAccountingCode	STRING(32)	NO			Accounting code provided by Merchant
startDate	DATE	NO			Start of Add On PLANNED
expiresAfterDate	DATE	NO			Date of expiration PLANNED
cancelledTs	TIMESTAMP	-			Timestamp of cancellation
archivedTs	TIMESTAMP	-			Timestamp of archivation
includeImplicitInAgreement	BOOLEAN	NO			Looking at the invoice, is the Add On amount included in the Agreement amount?

GET /addOn/{guid}

Get a single Add On.

Response

HTTP	Description
200	OK
404	Add On not found

HTTP 200 Example

{
	"addOnGuid" : "",
	"name" : "",
	"description" : "",
	"createdTs" : "",
	"subscriptionGuid" : "",
	"dataSetGuid" : "",
	"quantity" : "",
	"unit" : "",
	"unitPrice" : "",
	"amount" : "",
	"amountVat" : "",
	"amountTotal" : "",
	"vatPercentage" : "",
	"taxDeductable" : "",
	"state" : "",
	"externalId" : "",
	"purposeAccountingCode" : "",
	"expiresAfterDate" : "",
	"archivedTs" : "",
	"includeImplicitInAgreement" : "",
}

POST /addOn

Insert a single AddOn.

Request

The following must be provided as the request body:

{
	"subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"name" : "Gift",
	"description" : "A small gift",
	"quantity" : 1,
	"unit" : "pcs",
	"unitPrice" : 10.0,
	"amount" : 10.0,
	"amountVat" : 0.0,
	"amountTotal" : 10.0,
	"vatPercentage" : 0.0,
	"taxDeductable" : true,
	"externalId" : "xyz",
	"dataSetGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"purposeAccountingCode" : "gift",
	"expiresAfterDate" : "2020-01-01",
	"includeImplicitInAgreement" : false
}

Response

HTTP	Description
201	Created
400	Something's wrong with request body.

HTTP 200 Example

{
    "addOnGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "..." : "..."
}

PUT /addOn/{guid}

Update a single AddOn.

Request

The following must be provided as the request body:

{
	"name" : "Gift",
	"description" : "A small gift",
	"quantity" : 1,
	"unit" : "pcs",
	"unitPrice" : 10.0,
	"amount" : 10.0,
	"amountVat" : 0.0,
	"amountTotal" : 10.0,
	"vatPercentage" : 0.0,
	"taxDeductable" : true,
	"externalId" : "xyz",
	"dataSetGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"purposeAccountingCode" : "gift",
	"expiresAfterDate" : "2020-01-01",
	"includeImplicitInAgreement" : false
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	AddOn was not found

HTTP 200 Example

{
    "addOnGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "..." : "..."
}

POST /addOn/{guid}/Cancel

Cancels a single AddOn.

Response

HTTP	Description
200	OK
400	Bad request
404	Not found

POST /addOn/{guid}/Archive

Archives a single AddOn.

Response

HTTP	Description
200	OK
400	Bad request
404	Not found

AddOn States

Following is a list of AddOn states:

State	Description
Active	Subscription is active and will result in future Payments.
Inactive	Subscription is inactive.
Archived	Subscription was archived and is therefore hidden from queries.

4.0 Subscription

A Subscription represents the Contact's unique Subscription of a given Agreement (i.e. membership or recurring donation) and so is the engagement of an Agreement. It connects possible upgrades to the chosen Agreement and defines which Payment Method the Agreement and upgrade should be charged by.

Properties

Name	Type	Mandatory	Default	Example	Description
subscriptionGuid	STRING	-			Unique GUID
merchantId	STRING	-			Readble ID of the merchant
contactGuid	STRING	YES
agreementGuid	STRING	YES
state	STRING	YES			Please see list of Subscription States below
paymentMethodType	STRING	-			Please see list of Payment Method Types under Payment Method
paymentMethodGuid	STRING	YES			GUID of Payment Method
createdTs	DATETIME	-			Timestamp of Subscription creation
startDate	DATETIME	YES		"2020-01-01", but most commonly the current date.	Date from which OnlineFundraising should begin charging the Subscription. Please consider the difference between startDate and originTs when importing existing Subscriptions.
expiresAfterDate	DATETIME	NO			Date of expiration
cancelledTs	DATETIME	-			Timestamp of cancellation
cancelCode	INTEGER	-			Please see list of Cancel Codes below
cancelDescription	STRING	NO			User friendly description of cancellation or custom string provided by Merchant
holdDescription	STRING	NO			Custom string provided by Merchant
archivedTs	DATETIME	-			Timestamp of archivation
inactivatedTs	DATETIME	-			Timestamp of deactivation
quantity	INTEGER	NO	1		Defaults to 1
errorCode	INTEGER	-			Please see list of Subscription Error Codes below
errorDescription	STRING	-			User friendly description of the provided error
nextDueDate	DATETIME	-			Date of next planned charge calculated by Agreement schedule configuration
externalId	STRING	NO			An external ID
externalLink	STRING	NO			An external URL to e.g. CRM
originTs	DATETIME	NO			Non-operational timestamp of origin, useful when importing data.
dataSetGuid	STRING	NO			The DataSet GUID used to create the Contact

GET /subscriptions?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}&state={z}

Get a list of Subscriptions at a given size by a given offset and date limitation. Use "state" (see list of states below) to focus your query. All parameters are optional.

Response

HTTP	Description
200	OK

HTTP 200 Example

{
	"pageNumber" : {x},
	"pageSize" : {y},
	"startDate" : {yyyy-mm-dd},
	"endDate" : {yyyy-mm-dd},
	"list" : [
		{
			"subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		},
		{
			"subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		}
	]
}

GET /subscription/{guid}

Get a single Subscription.

Response

HTTP	Description
200	OK
404	Subscription not found

HTTP 200 Example

{
	"subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"version" : 1,
	"contactGuid" : "",
	"agreementGuid" : "",
	"state" : "",
	"paymentMethodType" : "",
	"paymentMethodGuid" : "",
    "createdTs" : "2019-01-01 00:00:00 +0100",
	"startDate" : "",
	"expiresAfterDate" : "",
	"cancelledTs" : "",
	"cancelCode" : "",
	"cancelDescription" : "",
	"holdDescription" : "",
	"archivedTs" : "",
	"quantity" : 1,
	"errorCode" : "",
	"errorDescription" : "",
	"nextDueDate" : "",
	"externalId" : "",
	"externalLink" : "",
	"dataSetGuid" : ""
}

POST /subscription

Insert a single Subscription.

Request

The following must be provided as the request body:

{
	"contactGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"agreementGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"paymentMethodType" : "",
	"paymentMethodGuid" : "",
	"startDate" : "",
	"expiresAfterDate" : "",
	"quantity" : 1,
	"externalId" : "",
	"externalLink" : ""
}

Response

HTTP	Description
201	Created
400	Something's wrong with request body.

HTTP 201 Example

{
    "subscriptionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "..." : "..."
}

PATCH /subscription/{guid} PLANNED

Update a single Subscription.

Request

The following must be provided as the request body:

[
	{
		"op" : "replace",
		"path" : "/quantity",
		"value" : 2
	}
]

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Subscription was not found

GET /subscription/{guid}/schedule

Get an array of five scheduled payment due dates, after the nextDueDate, for a single Subscription.

The example below correlates to a Monthly Subscription with the nextDueDate: 2019-05-01.

Response

HTTP	Description
200	OK
404	Subscription was not found

HTTP 200 Example

["2019-06-01","2019-07-01","2019-08-01","2019-09-01","2019-10-01"]

GET /subscription/{guid}/payments

Get a list of Payments for a single Subscription.

Response

HTTP	Description
200	OK
404	Subscription was not found

HTTP 200 Example

[
	{
		"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /subscription/{guid}/singleCosts

Get a list of /wiki/spaces/OFpublic/pages/4816985 for a single Subscription.

Response

HTTP	Description
200	OK
404	Subscription was not found

HTTP 200 Example

[
	{
		"singleCostGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"singleCostGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /subscription/{guid}/singleDiscounts

Get a list of /wiki/spaces/OFpublic/pages/327885 for a single Subscription.

Response

HTTP	Description
200	OK
404	Subscription was not found

HTTP 200 Example

[
	{
		"singleDiscountGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"singleDiscountGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /subscription/{guid}/addOns

Get a list of Add Ons for a single Subscription.

Response

HTTP	Description
200	OK
404	Subscription was not found

HTTP 200 Example

[
	{
		"addOnGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"addOnGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

POST /subscription/{guid}/singleCost

PLANNED

POST /subscription/{guid}/Hold

Hold a Subscription.

Request

The following can be provided as the request body:

{
	"holdDescription" : "...",
}

Response

HTTP	Description
200	OK
404	Subscription was not found

POST /subscription/{guid}/Restart

Restart a Subscription from Hold state.

Request

The following can be provided as the request body:

{
	"startDate" : "2019-01-01 00:00:00 +0100",
	"expiresAfterDate" : "2019-12-31 00:00:00 +0100",
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Subscription was not found

POST /subscription/{guid}/Cancel

Cancel a Subscription, but please note this does affect neither the Payment Method nor Pending Payments.

Request

The following can be provided as the request body:

{
	"cancelDescription" : "...",
}

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Subscription was not found

POST /subscription/{guid}/Archive

Archive a Subscription.

Response

HTTP	Description
200	OK
404	Subscription was not found

GET /subscription/{guid}/log?limit={limit}

Get a list of changes to a Subscription.

Response

HTTP	Description
200	OK

HTTP 200 Example

[
  {
    "changeGuid": "242bf0de-5ed3-48a1-bb3a-xxxxxxxxxxxx",
    "createdTs": "2021-01-01 00:00:00 +0100",
    "entityType": "Subscription",
    "entityGuid": "9a7c3665-5be0-4a5c-9641-xxxxxxxxxxxx",
    "changeTs": "2021-01-01 00:00:00 +0100",
    "oldEntityJson": "{ .. }",
    "changeDescription": "Updated by PUT request",
    "requester": "",
    "systemRequest": false,
    "changes": [
      {
        "newValue": "Inactive",
        "oldValue": "Active",
        "fieldName": "state"
      }
    ]
  }
]

Subscription States

Following is a list of Subscription states:

State	Description
Pending	Waiting for PaymentMethod to become active.
Active	Subscription is active and will result in future Payments.
Inactive	Subscription is inactive and is therefore not in consideration for future Payments.
Expired	Subscription has passed expiration date.
Archived	Subscription was archived and is therefore hidden from queries.
Error	Subscription has errorCode and errorDescription.

Subscription State Diagram

Subscription Error Codes and Descriptions

For further examples and ties to other entities, please see: Error and Cancel Codes

Error Code	Description	State
100001	Subscription has no active Payment Method, but Payments are required by the Agreement.	Active
100002	Subscription has no active Payment Method, and Payments are not required.	Inactive
100003	Subscription Payment Method not found at the time of scheduling.	Inactive

Subscription Cancel Codes

For further examples and ties to other entities, please see: Error and Cancel Codes

Cancel Code	Description	State
100101	Cancelled by Debtor.	Inactive
100102	Cancelled by Creditor in either UI or API integration.	Inactive
100103	Expired due to the defined expiresAfterDate.	Inactive
100104	Cancelled by System at the time og charge. Due to the Payment Method being cancelled at payment gateway.	Inactive

5.0 Payment Method

A Payment Method represents a valid method of charging the End User. This could either be an active card, an active Betalingsservice, or an active MobilePay Subscription.

Properties

Name	Type	Description
paymentMethodGuid	STRING	Unique GUID
paymentSessionGuid	STRING	GUID of Payment Session used internally
contactGuid	STRING	GUID of Contact
state	STRING	Please see list of Payment Method States below
paymentMethodType	STRING	Please see list of Payment Method Types below
paymentMethodAccountingCode	STRING	Accounting Code defined by Payment Method
paymentGatewayProvider	STRING	Please see list of Payment Gateway Providers below
paymentGatewayGuid	STRING	GUID of Payment Gateway used internally
paymentGatewaySubscriptionReferenceId	STRING	A token from the chosen Payment Gateway used for recurring payments
metaData	JSON Object	Contains metadata such as card type, masked card number etc. PLANNED
createdTs	DATE	Timestamp of Payment Method creation
cancelledTs	DATE	Timestamp of cancellation
cancelCode	INTEGER	Please see list of Cancel Codes below
cancelDescription	STRING	User friendly description of cancellation
expireTs	DATE	Timestamp of expiration
errorCode	INTEGER	Please see list of Payment Method Error Codes below
errorDescription	STRING	User friendly description of the provided error
gatewayErrorCode	INTEGER	Error code from Payment Gateway. Please see: Error and Cancel Codes
gatewayErrorDescription	STRING	Error description from Payment Gateway. Please see: Error and Cancel Codes
rawErrorString	STRING	Uninterpreted error response provided by Payment Gateway

GET /paymentMethod/{guid}

Get a single Payment Method.

Response

HTTP 200 Example

{
  "paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "paymentSessionGuid": "",
  "contactGuid": "",
  "state": "",
  "paymentMethodType": "",
  "paymentMethodAccountingCode": "",
  "paymentGatewayProvider": "",
  "paymentGatewayGuid": "",
  "paymentGatewaySubscriptionToken": "",
  "createdTs": "",
  "cancelledTs": "",
  "cancelCode": "",
  "cancelDescription": "",
  "expireTs": "",
  "errorCode": "",
  "errorDescription": "",
  "metaData": {
    "card": {
      "type": "Dankort",
      "expiresTs": "2020-01",
      "cardNumber": "457150XXXXXX7478",
      "acquirer": "Nets/Teller"
    },
    "bs": {
      "mandate": "956964XXX",
      "customerNumber": "605XXX"
    },
    "mps": {
      "externalId": "1568581537XXX"
    },
    "sms": {
      "msisdn": "4512345678"
    }
  }
}

POST /paymentMethod PLANNED

Since creation of Payment Methods usually requires interaction with the chosen Payment Gateway it is essentially not possible to create a Payment Method at distance.

However since it is still possible (as of January 2019) to create Betalingsservice without user interaction (using CPR, sort code and account number) the details of this endpoint is still to be sorted, but as a time limited solution due to a soon expected limitation by Betalingsservice. The details of this will follow.

POST /paymentMethod/{guid}/Cancel

Cancel a Payment Method, but please note this does not affect the Subscription and is not allowed if Pending Payments exists.

Request

The following must be provided as the request body:

{
	"cancelCode" : "...",
	"cancelDescription" : "...",
}

Response

HTTP	Description
202	Accepted
400	Bad Request
404	Payment Method not found

A callback is sent when the cancel operation either fails or succeeds.

Payment Gateway Providers

Payment Gateway Provider	Description
ePay	Delivers payments methods: Dankort, Visa, MasterCard, MobilePay Myshop etc. (recently bought by Bambora)
MobilePay	MobilePay Subscriptions
Betalingsservice	Betalingsservice (Basis and Total Solution)
LinkMobility	Delivers SMS payment method
SMSCPH	Delivers SMS payment method
Test	Used for testing purposes
Log	Only used in Sandbox for testing purposes

Payment Method Types

Payment Method	Description
Card	Single and Recurring payments via Dankort, Visa, MasterCard etc.
MobilePayOnline	Single payments via MobilePay Myshop (formerly MobilePay Online)
MobilePaySubscriptions	OneOff and Recurring payments via MobilePay Subscriptions
Betalingsservice	Recurring payments via Betalingsservice, inclusive Payment Slips (Indbetalingskort)
SMS	Single payments via SMS keywords
Test	Single and Recurring payments as Test
Log	Only used in Sandbox for testing purposes

Payment Method States

Following is a list of Payment Method states with a state diagram below:

State	Description
New	A Payment Method that has been created, but not yet sent to the payment gateway.
Pending	The request has been sent to chosen Payment Gateway
SessionExpired	Used for MobilePay Subscriptions that was not accepted in time.
Active	The Payment Method is active
Expired	The Payment Method is expired. Primarily used for cards.
Rejected	The Payment Method was rejected by the End User prior to activation.
Cancelled	The Payment Method was cancelled by the End User or Merchant.
Failed	The Payment Method reaches failed, if none of the above applies.

Payment Method State Diagram

Payment Method Error Codes and Descriptions

For further examples and ties to other entities, please see: Error and Cancel Codes

Error Code	Description	Examples	State
200001	Payment Method signup failed	Invalid data provided for either National ID, Business Number, Sort Code or Account Number with Betalingsservice.	Failed
200002	Payment Method was rejected during sign up	Involves Debtor rejection of a request i.e. in a mobile app.	Rejected
200003	Payment Method signup expired	Debtor did not approve request in mobile app in time.	SessionExpired
200004	Payment Method has expired	Involves expiration of Card or requirement of new SCA.	Expired
200005	Payment Method has failed	Errors with the Gateway without options to retry or reactive.	Failed

Payment Method Cancel Codes and Descriptions

For further examples and ties to other entities, please see: Error and Cancel Codes

Cancel Code	Description	State
200101	Cancelled by Debtor	Cancelled
200102	Cancelled by Creditor	Cancelled
200103	Cancelled by System	Cancelled

6.0 Payment

A Payment represents a single payment request by a set Contact.

Properties

Name	Type	Example	Description
paymentGuid	STRING	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID
createdTs	DATETIME	2019-01-01 00:00:00 +0100	Timestamp of Payment creation
paymentType	STRING	Single	Please see list of Payment Types below
contactGuid	STRING(64)	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	GUID of Contact
amount	DOUBLE	100.0	Amount charged
amountPaid	DOUBLE	100.0	The actual amount paid by the end user. It may diverse from amount on rare occasions.
state	STRING	Charged	Please see list of Payment States below
paymentMethodType	STRING		Please see list of Payment Method Types below
paymentRequired	BOOLEAN	false	Is the Payment required for the Subscription to be valid?
taxDeductable	BOOLEAN	true	Defines basis for tax deductibility
dueDateTs	DATETIME	2019-01-01 00:00:00 +0100	Timestamp of expected charge
chargedTs	DATETIME	2019-01-01 00:00:00 +0100	Timestamp of successful charge
failedTs	DATETIME	2019-01-01 00:00:00 +0100	Timestamp of charge failure
rejectedTs	DATETIME	2019-01-01 00:00:00 +0100	Timestamp of charge rejection
refundedTs	DATETIME	2019-01-01 00:00:00 +0100	Timestamp of successful refund
cancelledTs	DATETIME	2019-01-01 00:00:00 +0100	Timestamp of cancellation
errorCode	STRING	10001	Please see list of Payment Error Codes below
errorDescription	STRING	This is a friendly description	User friendly description of the provided error
currencyCode	STRING	DKK	ISO formatted Currency Code (wiki)
paymentGatewayProvider	STRING	Betalingsservice	Please see list of Payment Gateway Providers below
paymentGatewayReferenceId	STRING		Gateway reference GUID
paymentGatewayTransactionId	STRING		Gateway transaction ID (only relevant for ePay/Bambora)
metaData	JSON Object		Contains metadata such as card type, masked card number etc.
purposeAccountingCode	STRING(32)		A code that identifies the purpose of this agreement, with respect to accounting.
paymentMethodAccountingCode	STRING(32)		Accounting Code defined by Payment Method
amountRefunded	DOUBLE	0.0	Amount refunded
agreementGuid	STRING(64)	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	GUID of Agreement
subscriptionGuid	STRING(64)	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	GUID of Subscription
paymentMethodGuid	STRING(64)	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	GUID of Payment Method
paymentSessionGuid	STRING(64)	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	GUID of Payment Session used internally to identify the initial payment session
dataSetGuid	STRING(64)	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	A DataSet GUID containing metadata
externalId	STRING		An external ID to eg. CRM
externalLink	STRING		An external URL to e.g. CRM

GET /payments?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}&state={z}

Get a list of Payments with a given state, at a given size by a given offset and date limitation. All parameters are optional.

Response

HTTP	Description
200	OK

HTTP 200 Example

{
	"pageNumber" : {x},
	"pageSize" : {y},
	"startDate" : {yyyy-mm-dd},
	"endDate" : {yyyy-mm-dd},
	"list" : [
		{
			"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		},
		{
			"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		}
	]
}

GET /payments?search={paymentGatewayReferenceId}

Get an array of Payments by a given search string matching the paymentGatewayReferenceId.

Response

HTTP	Description
200	OK

HTTP 200 Example

[
	{
		"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /payment/{guid}

Get a single Payment.

Response

HTTP	Description
200	OK
404	Payment not found

HTTP 200 Example

{
  "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "createdTs": "2019-01-01 00:00:00 +0100",
  "paymentType": "",
  "contactGuid": "",
  "agreementGuid": "",
  "amount": 100.0,
  "taxDeductable": true,
  "state": "",
  "dueDateTs": "",
  "chargedTs": "",
  "failedTs": "",
  "errorCode": "",
  "errorDescription": "",
  "currencyCode": "DKK",
  "paymentGateway": "",
  "paymentGatewayReferenceId": "",
  "paymentGatewayTransactionId": "",
  "purposeAccountingCode": "",
  "paymentMethodAccountingCode": "",
  "amountRefunded": 0.0,
  "paymentMethodGuid": "",
  "subscriptionGuid": "",
  "paymentRequired": true,
  "paymentSessionGuid": "",
  "dataSetGuid": "",
  "externalLink": "",
  "metaData": {
    "card": {
      "type": "Dankort",
      "cardNumber": "457150XXXXXX7478",
      "acquirer": "Nets/Teller",
      "orderId": "4200xxxxx",
      "transactionId": "88821321"
    },
    "bs": {
      "customerNumber": "605XXX",
      "mandate": "956964XXX",
      "ocr": "1231352356235",
      "dataSupplierReferenceId": "GSFDGSERG",
	  "paymentSlipDispatchMethod": "195",
	  "transactionCode": "297"
    },
    "mps": {
      "externalId": "1568581537XXX"
    },
    "sms": {
      "msisdn": "4512345678"
    }
  }
}

GET /payment/{guid}/receipt

Get a single Payment's Receipt PLANNED

Response

HTTP	Description
200	OK
404	Payment not found

HTTP 200 Example

{
	"receiptGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "..." : "...",
}

GET /payment/{guid}/transactions

Get a list of Transactions for a single Payment.

Response

HTTP	Description
200	OK
404	Payment not found

HTTP 200 Example

[
	{
		"transactionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"transactionType" : "charge",
		"amount" : 100.0,
		"..." : "...",
	},
	{
		"transactionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"transactionType" : "refund",
		"amount" : 100.0,
		"..." : "...",
	}
]

GET /payment/{guid}/chargeAttempts

Get a list of Charge Attempts for a single Payment.

Response

HTTP	Description
200	OK
404	Payment not found

HTTP 200 Example

[
	{
		"chargeAttemptGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"chargeAttemptGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

GET /payment/{guid}/orderLines

Get a list of Order Lines for a single Payment PLANNED

Response

HTTP	Description
200	OK
404	Payment not found

HTTP 200 Example

[
	{
		"orderLineGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	},
	{
		"orderLineGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
		"..." : "...",
	}
]

PATCH /payment/{guid}

Update a single Payment using add, replace or remove operations.

Request

The following must be provided as the request body:

[
	{
		"op" : "add|replace|remove",
		"path" : "/externalId",
		"value" : "1001"
	}
]

Response

HTTP	Description
200	OK
400	Something's wrong with request body.
404	Payment was not found

POST /payment/{guid}/Refund

Refund a Payment.

Request

The following must be provided as the request body:

{
	"amount" : 100.0,
	"callbackUrl" : "https://yourdomain.tld/"
}

Response

HTTP	Description
202	Accepted
400	Bad Request
404	Payment not found

A callback is sent when the refund operation either fails or succeeds. Please see Refund for entity properties.

POST body example

{
	"paymentGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"transactionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
	"refundGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
}

POST /payment/{guid}/Cancel

Cancel a Pending Payment.

Response

HTTP	Description
202	Accepted
400	Bad Request
404	Payment not found

A callback is sent when the cancel operation either fails or succeeds.

Payment Gateway Providers

Payment Gateway Provider	Description
ePay	Delivers payments methods: Dankort, Visa, MasterCard, MobilePay Myshop etc. (recently bought by Bambora)
MobilePay	MobilePay Subscriptions
Betalingsservice	Betalingsservice (Basis and Total Solution)
LinkMobility	Delivers SMS payment method
SMSCPH	Delivers SMS payment method
Test	Used for testing purposes
Log	Only used in Sandbox for testing purposes

Payment Types

Payment Type	Description
Single	A single Payment without connection to any Subscription
Recurring	A recurring Payment adjacent to a Subscription
OneOff	An initial Payment adjacent to a Subscription

Payment Method Types

Payment Method	Description
Card	Single and Recurring payments via Dankort, Visa, MasterCard etc.
MobilePayOnline	Single payments via MobilePay Myshop (formerly MobilePay Online)
MobilePaySubscriptions	OneOff and Recurring payments via MobilePay Subscriptions
Betalingsservice	Recurring payments via Betalingsservice, inclusive Payment Slips (Indbetalingskort)
SMS	Single payments via SMS keywords
Test	Single and Recurring payments as Test
Log	Only used in Sandbox for testing purposes

Payment States

Following is a list of Payment states:

State	Description	Release
Planned	Planned payment represents a Payment with future due date and amount.	PLANNED
Ready	Result from processing of a pending Subscription.
AwaitingRetry	Charge attempt failed. Will retry if possible.
AwaitingCharge	Charge attempt has been created, but not yet sent to Payment Gateway
Pending	Request sent to Payment Gateway.
SessionExpired	Payment is expired. Used for MobilePay Subscriptions one-off that was not accepted in time.
Charged	Payment was successfully charged.
Failed	Payment failed.
Rejected	Payment request was rejected by Contact.
Cancelled	Payment was cancelled by Merchant after the payment request is sent to Payment Gateway and prior to the expected due date with Payment Gateway limitations in mind.
Refunded	Payment was successfully refunded.

Payment State Diagram for recurring payments

Payment State Diagram for single payments

Payment Cancel Codes

For further examples and ties to other entities, please see: Error and Cancel Codes

Error Code	Description	State
200101	Cancelled by Debtor	Cancelled
200102	Cancelled by Creditor	Cancelled

Payment Error Codes

For further examples and ties to other entities, please see: Error and Cancel Codes

Error Code	Description	Examples	State
200001	Payment Method signup failed	Invalid data provided for either National ID, Business Number, Sort Code or Account Number with Betalingsservice.	Failed
200002	Payment Method was rejected during sign up	Involves Debtor rejection of a request i.e. in a mobile app.	Rejected
200003	Payment Method signup expired	Debtor did not approve request in mobile app in time.	SessionExpired
200004	Payment Method has expired	Involves expiration of Card or requirement of new SCA.	Expired
200005	Payment Method has failed	Errors with the Gateway without options to retry or reactive.	Failed

7.0 Charge Attempt

A Transaction represents a single transaction in relation to a Payment

Properties

Name	Type	Description
chargeAttemptGuid	STRING	Unique GUID
createdTs	TIMESTAMP	Timestamp of Charge Attempt creation
paymentGuid	STRING	Unique GUID of Payment
paymentMethodGuid	STRING	Unique GUID of Payment Method
paymentGatewayGuid	STRING	Unique GUID of Payment Gateway
paymentGatewayProvider	STRING	Such as ePay, MobilePaySubscriptions, Betalingsservice, LinkMobility, Test
state	STRING	Current state of Charge Attempt
paymentGatewaySubscriptionReferenceId	STRING	Subscription token at Payment Gateway
paymentGatewayPaymentReferenceId	STRING	Payment token at Payment Gateway
attemptTs	TIMESTAMP	Timestamp of charge attempt
chargedTs	TIMESTAMP	Timestamp of successful charge
failedTs	TIMESTAMP	Timestamp of failure
rejectedTs	TIMESTAMP	Timestamp of Contact rejection
cancelledTs	TIMESTAMP	Timestamp of Merchant declination
expiredTs	TIMESTAMP	Timestamp of expiration
gatewayErrorCode	INTEGER	Error code from Payment Gateway. Please see: Error and Cancel Codes
gatewayErrorDescription	STRING	Error description from Payment Gateway. Please see: Error and Cancel Codes
rawErrorString	STRING	Uninterpreted error response provided by Payment Gateway

8.0 Transaction

A Transaction represents a single transaction in relation to a Payment

Properties

Name	Type	Example	Description
transactionGuid	STRING	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID
createdTs	TIMESTAMP		Timestamp of Transaction creation
paymentGuid	STRING		Unique GUID of Payment
amount	DOUBLE		Transaction amount
paymentGatewayProvider	STRING		Such as ePay, MobilePaySubscriptions, Betalingsservice, LinkMobility, Test
paymentGatewayGuid	STRING		Unique GUID of Payment Gateway
paymentGatewaySubscriptionReferenceId	STRING		Subscription token at Payment Gateway
paymentGatewayPaymentReferenceId	STRING		Payment token at Payment Gateway
transactionTs	TIMESTAMP		Timestamp of transaction
transactionType	STRING	Charge, Refund	Type of transaction
paymentMethodAccountingCode	STRING		Accounting Code defined by Payment Method
chargeAttemptGuid	STRING		Unique GUID of Charge Attempt
paymentMethodGuid	STRING		Unique GUID of Payment Method

GET /transactions?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}

Get a list of Transactions at a given size by a given 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" : [
		{
			"transactionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		},
		{
			"transactionGuid" : "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
			"..." : "...",
		}
	]
}

GET /transaction/{guid}

Get a single Transaction.

Response

HTTP	Description
200	OK
404	Transaction not found

HTTP 200 Example

{
    "transactionGuid": "8386b0c8-8210-4b12-a8df-xxxxxxxxxxxx",
    "merchantId": "merchant-name",
    "createdTs": "2020-01-10 14:51:23 +0100",
    "paymentGuid": "269916c5-bf4e-4fda-acf0-xxxxxxxxxxxx",
    "paymentMethodGuid": "24820946-9f48-4132-a8c5-xxxxxxxxxxxx",
    "chargeAttemptGuid": "d606d586-8abb-41d3-bbe0-xxxxxxxxxxxx",
    "amount": 100.0,
    "paymentGatewayProvider": "Test",
    "paymentGatewayGuid": "bfc19988-348d-4f40-b003-xxxxxxxxxxxx",
    "paymentGatewaySubscriptionReferenceId": "xxxxxxxxxxxx",
    "paymentGatewayPaymentReferenceId": "xxxxxxxxxxxx",
    "transactionTs": "2020-01-10 14:51:23 +0100",
    "transactionType": "Charge"
}

9.0 Refund

A Refund represents a single refund of a Transaction in relation to a Payment

Properties

Name	Type	Example	Description
refundGuid	STRING	a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx	Unique GUID
paymentGuid	STRING		Unique GUID of Payment
transactionGuid	STRING		Unique GUID of Transaction
createdTs	TIMESTAMP		Timestamp of Refund creation
state	STRING		See list LIST
paymentGateway	STRING		See list LIST
amount	DOUBLE		Amount of be refunded
refundedTs	TIMESTAMP		Timestamp of refunded amount
failedTs	TIMESTAMP		Timestamp of failure

GET /refund/{guid}

Get a single Refund.

Response

HTTP	Description
200	OK
404	Refund not found

HTTP 200 Example

{
	"refundGuid" : "",
	"paymentGuid" : "",
	"transactionGuid" : "",
	"createdTs" : "",
	"state" : "",
	"paymentGateway" : "",
	"amount" : "",
	"refundedTs" : "",
	"failedTs" : "",
}

10.0 Webhooks

Webhooks allow you to build or set up a web service (perhaps in relation to your CRM) which subscribes to certain events in OnlineFundraising.

When the listed events are triggered, OnlineFundraising will send a HTTP POST payload to the configured webhook URL from IPs listed here: https://s3.eu-central-1.amazonaws.com/dk.onlinefundraising.info/webhooks.json

Please note webhooks may be delivered twice in rare occasions, if connection problems, bad timings etc. is experienced. Please also see delivery attempts below.

Please also note webhooks currently can only be configured by sending an email to support@onlinefundraising.dk, including your webhook URL. Thanks

Event types

Below is a list of events triggering webhooks:

Entity	Event type	Description
contact	created	The Contact was created.
	updated	The Contact was updated.
	archived	The Contact was archived.
	merged	The Contact was merged into a target Contact. This callback will be sent for the Contact that is being archived.
agreement	created	The Agreement was created.
	updated	The Agreement was updated.
	archived	The Agreement was archived.
paymentMethod	created	The Payment Method was created.
	activated	The Payment Method was accepted by Contact
	updated	The Payment Method was updated by Merchant
	rejected	The Payment Method was rejected by Contact
	cancelled	The Payment Method was cancelled by Merchant or Contact
	failed	The Payment Method failed. Please see error description
	expired	The Payment Method expired
	sessionExpired	The Payment Method was expired. Used for MobilePay Subscriptions one-off that was not accepted in time.
subscription	created	The Subscription was created.
	activated	The Subscription was set active.
	updated	The Subscription was updated by Merchant.
	expired	The Subscription period ended.
	cancelled	The Subscription was cancelled by Merchant or Contact.
	onHold	The Subscription was paused by Merchant.
	restarted	The Subscription was restarted by Merchant.
payment	created	The Payment was created.
	charged	The Payment was charged.
	sessionExpired	The Payment was expired. Used for MobilePay Subscriptions one-off that was not accepted in time.
	rejected	The Payment was rejected by Contact.
	cancelled	The Payment was cancelled by Merchant.
	refunded	The Payment was refunded by Merchant.
	failed	The Payment failed.
addOn	created	The AddOn was created.
	updated	The AddOn was updated.
	cancelled	The AddOn was cancelled.
	archived	The AddOn was archived.
dataSet	created	The DataSet was created.
	updated	The DataSet was updated.

Webhook payload

One or more webhook objects may be delivered in a single request.

Example of POST delivery

[
	{
    	"merchantId": "fundraisingbureauet",
	    "webhookEventGuid": "22ce6765-461f-4dd2-a3eb-xxxxxxxxxxxx",
    	"webhookGuid": "592d0752-dfda-46b8-aeec-xxxxxxxxxxxx",
    	"webhookAttemptGuid": "029b8cb0-9825-466d-a9db-xxxxxxxxxxxx",
    	"entityGuid": "b1123c69-cb84-4adf-98cf-xxxxxxxxxxxx",
    	"entityType": "contact",
    	"eventType": "created"
	},
	{
    	"merchantId": "fundraisingbureauet",
	    "webhookEventGuid": "a1dfb689-3273-49b7-9f5f-xxxxxxxxxxxx",
    	"webhookGuid": "07a05b9b-a699-4bee-9afe-xxxxxxxxxxxx",
    	"webhookAttemptGuid": "89efde72-4c01-4dd7-89c6-xxxxxxxxxxxx",
    	"entityGuid": "8e449c62-9b9d-4776-a2da-xxxxxxxxxxxx",
    	"entityType": "payment",
    	"eventType": "updated"
	}
]

Webhook delivery attempts

Should your integration not respond at all or respond with a HTTP code other than 200 OK, then we will resend the webhook by an exponential backoff algorithm with the following seconds interval per attempt:

10
1800
3600
5400
7200
9000
10800
12600
14400
16200

Payment API

1.0 Contact

2.0 Agreement

3.0 AddOn

4.0 Subscription

5.0 Payment Method

6.0 Payment

7.0 Charge Attempt

8.0 Transaction

9.0 Refund

10.0 Webhooks