Payment API

Subscription

API Documentation

Senest redigeret:

Introduction

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

 

Endpoints

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

of-api-subscription.png

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