Payment API

Agreement

API Documentation

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 muchwhen 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

 

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",
  "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 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.