How may we help?

Welcome to the support universe of OnlineFundraising where you will find help and guidance through our articles and videos. Please have a look and use the search function as needed. You are always welcome to contact our support in case there are any questions left unanswered.

Payment API

Agreement

Senest redigeret:

Introduction

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.

Endpoints

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",
  "merchantId": "your-organisation",
  "createdTs": "2019-01-01 00:00:00 +0100",
  "state": "Available",
  "name": "Membership",
  "description": "Youth",
  "purposeAccountingCode": "youth-membership",
  "defaultQuantity": 1,
  "unit": "pcs",
  "unitPrice": 100.0,
  "amount": 100.0,
  "amountVat": 25.0,
  "amountTotal": 125.0,
  "vatPercentage": 25.0,
  "currencyCode": "DKK",
  "taxDeductable": false,
  "scheduleType": "Monthly",
  "scheduleBaseTier": 1,
  "scheduleFixedDay": 1,
  "scheduleEveryOther": 1,
  "scheduleCalendarUnit": "Month",
  "scheduleSelectedSet": "[1,2,5,6,7,12]",
  "communicationCollectionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

 

POST /agreement

Insert a single Agreement.

Request

The following must be provided as the request body:

{
  "name": "Membership",
  "description": "Youth",
  "purposeAccountingCode": "youth-membership",
  "defaultQuantity": 1,
  "unit": "pcs",
  "unitPrice": 100.0,
  "amount": 100.0,
  "amountVat": 25.0,
  "amountTotal": 125.0,
  "vatPercentage": 25.0,
  "currencyCode": "DKK",
  "taxDeductable": false,
  "scheduleType": "Monthly",
  "scheduleBaseTier": 1,
  "scheduleFixedDay": 1,
  "scheduleEveryOther": 1,
  "scheduleCalendarUnit": "Month",
  "scheduleSelectedSet": "[1,2,5,6,7,12]",
  "communicationCollectionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "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": "",
  "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",
  "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, 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"
      }
    ]
  }
]

Schema

Property Format and Description
agreementGuid

string<uuid>

Unique Guid
contactGuid

string<uuid>

Unique Guid
communicationCollectionGuid

string<uuid>

Unique Guid
dataSetGuid

string<uuid>

Unique Guid
default_quantity
 

integer

TO BE DEPRECATED. Default quantity = 1.
createdTs

string<yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of creation
updatedTs

string<yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of update
archivedTs

string<yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of archivation
merchantId

string

Unique ID of merchant

name

required

string

The name of the record
description

string

Description of the record

unit

required

string

TO BE DEPRECATED. Type of unit

unitPrice

required

number

TO BE DEPRECATED. Unit price of a single AddOn

amount

required

number

Summarised amount excluding VAT

amountVat

required

number

TO BE DEPRECATED. Amount VAT

amountTotal

required

number

TO BE DEPRECATED. Total amount including VAT

vatPercentage

required

number

TO BE DEPRECATED. VAT percentage

currencyCode

required

string

ISO formatted Currency Code
state

string

Enum: "Available", "Archived"
taxDeductible

boolean

Defines basis for tax deductibility
purposeAccountingCode

string

Accounting code provided by Merchant

scheduleType

required

string

See below for allowed schedule types.

scheduleBaseTier

required

 integer
The offset in relation to the chosen calendarUnit.
A Yearly subscription in March has baseTier: 3

scheduleFixedDay

required

integer
 

The offset day of the chosen calendarUnit.
A subscription the 15th has fixedDay: 15
Please note we do not accept the 29-31 of any month.

scheduleEveryOther

required

integer
 

The interval of the chosen calendarUnit.
Yearly : everyOther = 12
Monthly : everyOther = 1
scheduleCalendarUnit

string

Default: "Month"

Due date is calculated by the chosen calendarUnit.

Enum: "Day", "Week", "Month"
scheduleSelectedSet

string

Only relevant for Custom scheduleType.
A subscription in March, August and September has selectedSet: [3,8,9]
externalId

string

An external ID as provided by merchant
originTs

string<yyyy-MM-dd HH:mm:ss zzzz>

Timestamp of origin, useful when importing data (e.g. if originated in external system)

 

Example

{
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"communicationCollectionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"archivedTs": "2019-12-31 15:59:59 +0100",
"merchantId": "your-merchant",
"name": "Recurring donation",
"description": "Custom regular donation",
"default_quantity": 1,
"unit": "pcs",
"unitPrice": 100,
"amount": 100,
"amountVat": 0,
"amountTotal": 100,
"vatPercentage": 0,
"currencyCode": "DKK",
"state": "Available",
"scheduleType": "Custom",
"scheduleBaseTier": 1,
"scheduleFixedDay": 2,
"scheduleEveryOther": 1,
"scheduleCalendarUnit": "Day",
"scheduleSelectedSet": "[1,4,5,11]",
"externalId": "some-id",
"originTs": "2019-12-31 15:59:59 +0100",
"purposeAccountingCode": "donation"
}

 

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 DEPRECATED. Monthly occurrence on the 1st of given month
QuarterlyFirst DEPRECATED. Quarterly occurrence on the 1st of given month
HalfyearlyFirst DEPRECATED. Biannual occurrence on the 1st of given month
YearlyFirst DEPRECATED. 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 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 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 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 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 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 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.

Was this article helpful?

0 out of 0 found this helpful

Related articles