Payment API

Created by Christian Laugesen

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.

Changes committed to a Contact can be retrieved via the ChangeLog entity.

Properties

Name

Type

Mandatory

Default

Example

Description

contactGuid

STRING

-

Unique GUID

merchantId

STRING

-

Readable ID of the merchant

name

STRING

NO

OnlineFundraising 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

Finsensvej 6E, 2.

Address

address2

STRING

NO

Address line 2

postCode

STRING

NO

2000

Postcode

city

STRING

NO

Frederiksberg

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

OnlineFundraising 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

anonymizedTs

TIMESTMAP

-

Timestamp of anonymisation.

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

POST /contact/{guid}/Unmerge

Unmerge two Contacts that were previously merged by specifying the guid of the Archived Contact. The endpoint will restore the archived Contact to its previous state with references to related entities.

Webhooks with type “Updated” will be sent for the unmerged Contact.

HTTP

Description

200

OK

400

Something's wrong with request body or the specified Contact has not been merged

404

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

Changes committed to an Agreement can be retrieved via the ChangeLog entity.

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} 

Update a single Agreement. The following fields are patchable: name, description, defaultQuantity, unit, taxDeductable, paymentRequired, externalId, purposeAccountingCode and communicationCollectionGuid

Request

The following must be provided as the request body:

[
  {
    "op": "replace",
    "path": "/name",
    "value": "New agreement name"
  }
]

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

expiresAfterDate

DATE

NO



Date of expiration

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.

Changes committed to a Subscription can be retrieved via the ChangeLog entity.

Properties

Name

Type

Mandatory

Default

Example

Description

subscriptionGuid

STRING

-



Unique GUID

merchantId

STRING

-



Readable 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 archiving

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}

Update a single Subscription. The following fields are patchable: expiresAfterDate, holdDescription, quantity, externalId and externalLink.

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

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}/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

POST /subscription/{guid}/ChangeAgreement

Change the Agreement of a Subscription. A new startDate and nextDueDate is calculated for the Subscription based on the new Agreement.
Triggers a Subscription updated webhook.

Request

The following must be provided as the request body:

{
  "agreementGuid": "a6195e22-f9c3-xxxx-9da6-4cb4d1fff778" 
}

Response

HTTP

Description

200

OK

400

Something's wrong with request body

404

Subscription was not found

HTTP 200 Example

{
  "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "createdTs": "2021-06-10 13:43:10",
  "agreementGuid": "a6195e22-f9c3-xxxx-9da6-4cb4d1fff778",
  ... : ...
}


POST /subscription/{guid}/UpdatePaymentMethod

Update the PaymentMethod of a Subscription. A new startDate and nextDueDate is calculated for the Subscription based on the new PaymentMethod.
Triggers a Subscription updated webhook.

Request

The following must be provided as the request body:

{
  "paymentMethodGuid": "71209531-xxxx-xxxx-xxxx-49c0f59f1bfc" 
}

Response

HTTP

Description

200

OK

400

Something's wrong with request body

404

Subscription was not found

HTTP 200 Example

{
  "subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "createdTs": "2021-06-10 13:43:10",
  "paymentMethodGuid": "71209531-xxxx-xxxx-xxxx-49c0f59f1bfc",
  ... : ...
}

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 of 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. Please see list below

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.

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 Online 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 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 Accounting Codes (examples)

Payment Method Accounting Code

Description

BetalingsserviceMandate

Betalingsservice by bank

BetalingsservicePaymentSlip

Betalingsservice by payment slip (giro / FI-card)

Dankort

Dankort

Forbrugsforeningen

Forbrugsforeningen

Maestro (foreign)

Maestro from countries other than Denmark

Mastercard

Mastercard

Mastercard (foreign)

Mastercard from countries other than Denmark

MobilePay

MobilePay

Visa

Visa

Visa Electron

Visa Electron

Visa/Dankort

Visa or Dankort

Visa/Electron (foreign)

Visa/Electron from countries other than Denmark

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.

Inactive

The Payment Method is inactive

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. Please see example list under 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 Online 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 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

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

Example

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

Mandatory

Default

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 a HTTP POST payload is sent to the configured webhook URL from IPs listed here: https://s3.eu-central-1.amazonaws.com/dk.onlinefundraising.info/webhooks.json

Please note that 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 or respond with a HTTP code other than 200 OK we will resend the webhook by an exponential backoff algorithm with the following seconds interval per attempt:

  1. 10

  2. 1800

  3. 3600

  4. 5400

  5. 7200

  6. 9000

  7. 10800

  8. 12600

  9. 14400

  10. 16200

11.0 ChangeLog

A ChangeLog represents a change in an entity, such that the changes are transparent and traceable over time. A single ChangeLog entity can be used to reason what, why, when and by whom an entity was changed.

ChangeLogs can be of the following types:

  • Contact

  • Subscription

  • Agreement

  • AddOn

Properties

Name

Type

Example

Description

changeGuid

STRING(64)

c003d62e-b13b-4651-9b7b-xxxxxxxxxxxx

Unique GUID

createdTs

TIMESTAMP

Timestamp of ChangeLog creation

entityType

ENUM

Contact

The type of entity that has been changed.
Available options:
Contact | Subscription | Agreement | AddOn

entityGuid

STRING(64)

bd63f62e-d55a-4651-9b7b-xxxxxxxxxxxx

Unique GUID of the entity that has been changed

changeTs

TIMESTAMP

Timestamp of when the entity was changed

oldEntityJson

JSON

JSON representation of the entity before any of the changes were applied to it

changeDescription

STRING

“Subscription processed”

Textual description of the change

changeMetaData

JSON

Meta data of changes

requester

STRING

“individual@your-ngo.org” or “API”

Description of the person or system that triggered the change.
Empty if change was triggered internally within OnlineFundraising.

requesterIp

STRING

18.195.xx.xxx

The IP address of whomever responsible for triggering the change.
Empty if change was triggered internally within OnlineFundraising.

systemRequest

BOOLEAN

Boolean denoting whether the change was triggered by OnlineFundraising

keysOnly

BOOLEAN

Boolean denoting whether only the keys of an entity should be logged. Utilized when anonymizing contacts.

changes

JSON

JSON representation of the changes that were applied to the entity. Only contains the fields that were changed. Has data on both the old and new values.

Endpoints

For each entity type that supports logging changes there exist an endpoint for which the ChangeLogs of a specific entity can be retrieved.

Entity

Operation

Endpoint

QueryParam (Optional)

Contact

GET

https://payment.api.v3.onlinefundraising.dk/contact/{contactGuid}/log

?limit=x

Subscription

GET

https://payment.api.v3.onlinefundraising.dk/subscription/{subscriptionGuid}/log

?limit=x

Agreement

GET

https://payment.api.v3.onlinefundraising.dk/agreement/{agreementGuid}/log

?limit=x

By specifiying the query parameter “limit” it can be controlled how many ChangeLogs to retrieve. Default is no limit. ChangeLogs are returned sorted with the most recent first.

Response

HTTP

Description

200

OK

HTTP 200 Example

[
    {
        "changeGuid": "16b48073-xxxx-xxxx-xxxx-0a337c4ba4dc",
        "createdTs": "2021-04-23 10:26:07 +0200",
        "entityType": "Subscription",
        "entityGuid": "1222ac4a-xxxx-xxxx-xxxx-bb9df2b9ab53",
        "changeTs": "2021-04-23 10:26:07 +0200",
        "oldEntityJson": "{\"subscriptionGuid\":\"1222ac4a-xxxx-xxxx-xxxx-bb9df2b9ab53\",\"merchantId\":\"your-ngo\", ...}",
        "changeDescription": "Cancel subscription",
        "changeMetaData": "{}",
        "requester": "individual@your-ngo.org",
        "systemRequest": false,
        "changes": [
            {
                "newValue": 100102,
                "fieldName": "cancelCode"
            },
            {
                "newValue": "anden årsag",
                "fieldName": "cancelDescription"
            },
            {
                "newValue": "2021-04-23 10:26:06 +0200",
                "fieldName": "cancelledTs"
            },
            {
                "newValue": "2021-04-23 10:26:06 +0200",
                "fieldName": "inactivatedTs"
            },
            {
                "newValue": "Inactive",
                "oldValue": "Active",
                "fieldName": "state"
            }
        ],
        "keysOnly": false,
        "requesterIp": "18.195.xx.xxx"
    }
]