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

Subscription

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.

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": 1,
  "pageSize": 50,
  "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",
"merchantId": "your-merchant",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"state": "Pending",
"paymentMethodType": "Card",
"paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"startDate": "2019-12-31 15:59:59 +0100",
"expiresAfterDate": "2019-01-01",
"cancelledTs": "2019-12-31 15:59:59 +0100",
"cancelCode": 100101,
"cancelDescription": "string",
"holdDescription": "Donor requested to put subscription on hold",
"archivedTs": "2019-12-31 15:59:59 +0100",
"inactivatedTs": "2019-12-31 15:59:59 +0100",
"quantity": 1,
"errorCode": 100001,
"errorDescription": "string",
"nextDueDate": "2019-01-01",
"externalId": "some-id",
"externalLink": "string",
"originTs": "2019-12-31 15:59:59 +0100",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

 

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",
"merchantId": "your-merchant",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"state": "Pending",
"paymentMethodType": "Card",
"paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"startDate": "2019-12-31 15:59:59 +0100",
"expiresAfterDate": "2019-01-01",
"cancelledTs": "2019-12-31 15:59:59 +0100",
"cancelCode": 100101,
"cancelDescription": "string",
"holdDescription": "Donor requested to put subscription on hold",
"archivedTs": "2019-12-31 15:59:59 +0100",
"inactivatedTs": "2019-12-31 15:59:59 +0100",
"quantity": 1,
"errorCode": 100001,
"errorDescription": "string",
"nextDueDate": "2019-01-01",
"externalId": "some-id",
"externalLink": "string",
"originTs": "2019-12-31 15:59:59 +0100",
"dataSetGuid": "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",
"merchantId": "your-merchant",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"state": "Pending",
"paymentMethodType": "Card",
"paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"startDate": "2019-12-31 15:59:59 +0100",
"expiresAfterDate": "2019-01-01",
"cancelledTs": "2019-12-31 15:59:59 +0100",
"cancelCode": 100101,
"cancelDescription": "string",
"holdDescription": "Donor requested to put subscription on hold",
"archivedTs": "2019-12-31 15:59:59 +0100",
"inactivatedTs": "2019-12-31 15:59:59 +0100",
"quantity": 1,
"errorCode": 100001,
"errorDescription": "string",
"nextDueDate": "2019-01-01",
"externalId": "some-id",
"externalLink": "string",
"originTs": "2019-12-31 15:59:59 +0100",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

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",
"merchantId": "your-merchant",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"state": "Pending",
"paymentMethodType": "Card",
"paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"startDate": "2019-12-31 15:59:59 +0100",
"expiresAfterDate": "2019-01-01",
"cancelledTs": "2019-12-31 15:59:59 +0100",
"cancelCode": 100101,
"cancelDescription": "string",
"holdDescription": "Donor requested to put subscription on hold",
"archivedTs": "2019-12-31 15:59:59 +0100",
"inactivatedTs": "2019-12-31 15:59:59 +0100",
"quantity": 1,
"errorCode": 100001,
"errorDescription": "string",
"nextDueDate": "2019-01-01",
"externalId": "some-id",
"externalLink": "string",
"originTs": "2019-12-31 15:59:59 +0100",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

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"
      }
    ]
  }
]

Schema

Property Format and Description
subscriptionGuid

string <uuid>

Unique Guid
merchantId

string

Unique ID of merchant

contactGuid

required

string <uuid>

Unique Guid

agreementGuid

required

string <uuid>

Unique Guid

state

required

string

State of subscription

Enum: "Pending", "Active", "Inactive", "Expired", "Archived"
paymentMethodType
required

string

Type of payment method

Enum: "Card", "MobilePaySubscriptions", "MobilePayExternal", "VippsMobilePayRecurring", "Betalingsservice", "DirectDebit", "SMS", "Test", "Log"

paymentMethodGuid

required

string <uuid>

Unique Guid
createdTs

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

Timestamp of creation
updatedTs

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

Timestamp of update

startDate

required

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

Timestamp of update
expiresAfterDate

string <yyyy-MM-dd>

Date of expiration
cancelledTs

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

Timestamp of cancellation
cancelCode

integer

Cancel code

Enum: 100101, 100102, 100103, 100104
cancelDescription

string

User friendly description of cancellation or custom string provided by Merchant
holdDescription

string

Custom string provided by Merchant
archivedTs

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

Timestamp of archivation
activatedTs

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

Timestamp of activation
inactivatedTs

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

Timestamp of inactivation
quantity

integer

TO BE DEPRECATED. Quantity
errorCode

integer

Error code

Enum: 100001, 100002, 100003
errorDescription

string

Subscription has no active Payment Method, but Payments are required by the Agreement.
nextDueDate

string <yyyy-MM-dd>

Next due date
externalId

string

An external ID as provided by merchant
externalLink

string

An external URL to e.g. CRM
originTs

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

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

string <uuid>

Unique Guid

 

Example

{
"subscriptionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"merchantId": "your-merchant",
"contactGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"agreementGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"state": "Pending",
"paymentMethodType": "Card",
"paymentMethodGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"createdTs": "2019-12-31 15:59:59 +0100",
"updatedTs": "2019-12-31 15:59:59 +0100",
"startDate": "2019-12-31 15:59:59 +0100",
"expiresAfterDate": "2019-01-01",
"cancelledTs": "2019-12-31 15:59:59 +0100",
"cancelCode": 100101,
"cancelDescription": "string",
"holdDescription": "Donor requested to put subscription on hold",
"archivedTs": "2019-12-31 15:59:59 +0100",
"inactivatedTs": "2019-12-31 15:59:59 +0100",
"quantity": 1,
"errorCode": 100001,
"errorDescription": "string",
"nextDueDate": "2019-01-01",
"externalId": "some-id",
"externalLink": "string",
"originTs": "2019-12-31 15:59:59 +0100",
"dataSetGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

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

 

Was this article helpful?

0 out of 0 found this helpful

Related articles