Documentation

1Subscriptions

After a product and a subscriber has been created, the subscriber has to be subscribed to a subscription.

1.1Create Subscriptions via the Backend

You can create subscriptions directly via the backend. For this you have to navigate to Space > Subscription.

iframe
Figure 1. Select a subscriber and a product in the backend.

First, you have to select the subscriber that you want to subscribe to a product. On the subsequent page you will be presented with an additional dialog that asks for a reference and provides an overview over the monthly costs that you defined in the product.

iframe
Figure 2. Configure the subscription for the subscriber.
Note
In this example no token is present and selected. This will trigger a Charge Flow where the an email will be sent to the subscriber asking for his payment details. In case you have this payment information already stored in a valid token, it is important that you select the token here. More information about token creation can be found in the tokenization documentation.

1.2Web Service API

A subscription can also be created via the web service API. there are two ways to initialize a subscription.

1.2.1Overview

We have to distinguish between two different forms how subscriptions can be initialized:

  1. You integrate the subscription service in your web site with a boarding process where the subscriber is present and you want to collect his payment details right away. In this case you will have to use the service initializeSubscriberPresent. This will create a confirmed payment transaction that can be used to build the Payment Page URL or the Java Script as described in the Iframe Documentation respectively the Payment Page documentation.

  2. You can also use Charge Flows to initialize a subscription. In this case you use the initialize Service. More about Charge Flows in the Charge Flow Documentation

See the following sample request to find out how you have to combine the requests.

1.2.2Create Token

It is possible to create a subscription with a specific token. When the token is already initialized and ready to be used the creation of the subscription does not require any input from the subscriber. When you do not provide a token we create a token along the subscription. The newly created token is not initialized. As such it requires that the user provides the payment information. This can be done through the initial transaction of the subscription.

Beside let the system create the token it can be created manually and assigned to the subscription.

1.2.2.1Create Token via the Backend

Tokens can be created via the backend under Space > Payment > Tokens. Click there to create a new token.

1.2.2.2Create Token via the Web Service API

Tokens can also be created via the web service API by using the create operation on the Token Service.

Request

{
    "enabledForOneClickPayment": true,
    "externalId": "customer-id-1",
    "tokenReference": "customer-id-1"
}
Note
The externaId has to be unique. If you send the externalID again the token will be updated.
Note
If you update entities you have to increase the version property in order to maintain consistency.

1.2.3Create Subscription

A subscription can also be created over the API. In order to do this you will have to use Subscription Service.

{
    "currency": "EUR",
    "product": {
        "id": 2
    },
    "selectedComponents": [
        {
            "id": 4
        },
        {
            "id": 2
        }
    ],
    "subscription": {
        "reference": "subscription-subscriber-101",
        "subscriber": {
            "id": 2
        },
        "token": {
            "id": 3
        }
    }
}

This will create a subscription in PENDING state with the specified product components and properties. As next steps we have to Initialize the subscription. This can be done in two ways.

  1. Generally you have the subscriber present in your application and you want him to provide the payment details directly in the boarding process. In this case you use the initializeSubscriberPresent Operation on the Subscription Service

  2. In case your subscriber is not present you can also send him a payment link via the Charge Flow where he will be asked to provide his payment information. In this case you use the initialize operation on the Subscription Service

1.2.4Initialize a subscription with the Subscriber Present

Once the subscription is created we can initialize the transaction with the initializeSubscriberPresent Operation on the Subscription Service.

Request

POST request to the following endpoint:

/api/subscription/initializeSubscriberPresentspaceId=1&subscriptionId=2&successUrl=http://www.yoursuccessurl.com&failedUrl=http://www.yourfailedurl.com

Response

{
	"createdOn": "2017-04-26T12:08:37.602Z",
	"discardedBy": 0,
	"externalId": "subscription-2",
	"failedUrl": "http://www.yourfailedurl.com",
	"id": 2,
	"ledgerEntries": [],
	"linkedSpaceId": 1,
	"plannedExecutionDate": "2017-04-26T12:08:37.152Z",
	"plannedPurgeDate": "2017-05-12T12:08:37.333Z",
	"processingType": "SYNCHRONOUS",
	"state": "PROCESSING",
	"subscription": {
		"createdOn": "2017-04-25T07:59:59.557Z",
		"description": null,
		"id": 2,
		"initializedOn": "2017-04-26T12:08:37.146Z",
		"language": "en-GB",
		"linkedSpaceId": 1,
		"reference": "subscription-subscriber-101",
		"state": "INITIALIZING",
		"subscriber": {
			"additionalAllowedPaymentMethodConfigurations": [],
			"billingAddress": null,
			"description": "",
			"disallowedPaymentMethodConfigurations": [],
			"emailAddress": "sascha.kruesi@cutomweb.com",
			"externalId": "8aae9fa2-9879-46bc-9d23-4e1b1c215931",
			"id": 2,
			"language": "en-GB",
			"linkedSpaceId": 1,
			"reference": "",
			"state": "ACTIVE",
			"version": 0
		},
		"token": {
			"createdOn": "2017-04-25T07:50:15.596Z",
			"customerEmailAddress": null,
			"customerId": null,
			"enabledForOneClickPayment": true,
			"externalId": "customer-id-2",
			"id": 3,
			"linkedSpaceId": 1,
			"state": "ACTIVE",
			"tokenReference": "customer-id-2",
			"version": 2
		},
		"version": 1
	},
	"succeedOn": null,
	"successUrl": "http://www.yoursuccessurl.com",
	"transaction": {
		"allowedPaymentMethodBrands": [],
		"allowedPaymentMethodConfigurations": [
			1
		],
		"authorizationAmount": 0,
		"chargeRetryEnabled": true,
		"completedOn": null,
		"confirmedBy": 0,
		"confirmedOn": "2017-04-26T12:08:37.593Z",
		"createdBy": 0,
		"createdOn": "2017-04-26T12:08:37.333Z",
		"currency": "EUR",
		"customerEmailAddress": "sascha.kruesi@cutomweb.com",
		"customerId": "2",
		"customersPresence": "VIRTUAL_PRESENT",
		"endOfLife": "2017-05-10T12:08:37.333Z",
		"failedOn": null,
		"failedUrl": "http://www.yourfailedurl.com",
		"group": {
			"beginDate": "2017-04-26T12:08:37.352Z",
			"customerId": "2",
			"id": 2,
			"linkedSpaceId": 1,
			"plannedPurgeDate": "2017-04-26T12:13:37.352Z",
			"state": "PENDING",
			"version": 1
		},
		"id": 2,
		"language": "en-GB",
		"lineItems": [],
		"linkedSpaceId": 1,
		"merchantReference": "2",
		"plannedPurgeDate": "2017-05-10T12:08:37.333Z",
		"refundedAmount": 0,
		"state": "CONFIRMED",
		"successUrl": "http://www.yoursuccessurl.com",
		"token": {
			"createdOn": "2017-04-25T07:50:15.596Z",
			"customerId": null,
			"enabledForOneClickPayment": true,
			"externalId": "customer-id-2",
			"id": 3,
			"linkedSpaceId": 1,
			"state": "ACTIVE",
			"tokenReference": "customer-id-2",
			"version": 2
		},
		"version": 2
	},
	"type": "AUTOMATIC",
	"version": 1
}

This will create a payment transaction that is in the state confirmed. The transaction id that is returned in the response can now be used to either buildJavaScriptUrl or buildPaymentPageUrl and create an IFrame or Payment Page authorization.

Example

In the example we use the GET Request to buildPaymentPageURL to get the URL where you redirect your merchant to provide the payment information and complete the initialization of the subscription. When the transaction is in the state fulfill the subscription will switch into the state Active. This will also create an active subscription version.

1.2.5Initialize the Subscription Using a Charge Flow

You can also initialize a subscription with a Charge Flow. In this case you use the initialize operation on the Subscription Service.

This will automatically trigger a Charge Flow and request the payment information from your subscriber in case you did not provide a token or the token is not valid.

Note
You now have a subscriber subscribed to a product! Behind the scenes, we create a ledger where we keep track of the charges that occur during a period. Every period the ledger will be reconciled and the outstanding amount will be charged to the customer. This will create a transaction and an associated invoice. The invoice outlines what the customer owes, reflects when they will be or were charged, and tracks the payment status. You can add additional items charges on this ledger via the API or in the backend. More information can be found in the billing section.

1.3Terminate Subscriptions

Subscriptions can be terminated with the terminate operation in the Subscription Service. You have the option to respect the termination period or to terminate the subscription immediately. When the termination period is respected the subscription will run the specified number of termination periods on the product version until the subscription finally terminates. When you choose to terminate the subscription immediately the subscription will be stopped and the period fee will be calculated pro rata and a charge with the outstanding amount will be triggered. If you terminate a subscription the subscription will be moved into the terminating state where the outstanding amounts will be charged. Once the last charge is successfully completed we move the subscription into the terminated state.

Request

spaceId=1&subscriptionId=2&respectTerminationPeriod=true

2Changing a Subscription

Typically a subscription changes over time. There are multiple reasons for a change. Either the user wants a different plan (e.g. switch from the basic plan to the pro plan) or the product itself changes. A product change may require that the subscription is updated to the latest product version.

A change can be applied immediately or as per the termination period. When an immediate change is issued the current running period is terminated and the outstanding amounts are charged. Period fees are calculated pro rata in this case. Setup fees are treated specially see Upgrading & Downgrading.

A change can be applied either via the API or over the backend.

2.1Change Subscriptions in the Backend

Subscriptions can be changed via the backend by editing the subscriptions. You can select the new product and define if the termination period should be considered. This leads to the creation of a new subscription version for the subscriber that will be active depending on the termination setting.

2.1.1Change Subscriptions via the API

You can also initiate a subscription change via the web service API by using the applyChanges operation on the Subscription Service

The request below will update my subscription with ID 8 to the new pro product with ID 3. This changes will take effect immediately.

Request

{
    "currency": "CHF",
    "product": {
        "id": 3
    },
    "respectTerminationPeriod": false,
    "selectedComponents": [
        {
            "id": 14
        }
    ],
    "subscription": {
        "id": 8
    }
}

2.2Downgrading & Upgrading

Setup fees locking the subscriber. However, the locking between switching products should be reduced. Therefore typically the setup fees get reimbursed when switching between products. For example when switching from the basic plan to the pro plan the subscriber does not need to pay the full setup fees of the pro plan again. There is a discount granted. We call this process of switching between products with setup fees upgrading resp. downgrading. An update of the product version may also lead to an upgrade or downgrade.

The following sections are only relevant when the product has setup fees.

The illustration below helps to show how downgrades and upgrades are calculated.

iframe
Figure 3. How are upgrades or downgrades calculated.

If you are performing an upgrade or a downgrade is determined by two parameters:

  • weight: The weight can be set on the product component.

  • product-reference: The product reference is also set on the product component.

In case you change a subscription we compare the components of the old and the new product version.

  1. Initially the setup fee of the new product version will be charged to the subscriber. In the illustration above you see that the new product version has a setup fee of 150 EUR for the Support Pro Component. So this will be charged immediately after the change is carried out.

  2. Based on the weight and the settings on the component in the old product version, there will be an upgrade or downgrade credit to his ledger. In the illustration above we set on the component Support that there will be a 50 EUR credit in case of an upgrade.

  3. First of all we check if the component was already present in the old product version in the same component group. If we find the reference we compare the weights to determine if it is in upgrade or downgrade.

  4. As the weight of the component Support Pro is higher the change is considered as upgrade and the 50 EUR will be credited to the ledger of the subscriber.

  5. In case a new component is added to the component group that was not present in the old product version no credit will be carried out.

The change in the subscription version of the subscriber results in a credit that can be seen on the subscription ledger of the subscriber.

iframe
Figure 4. See the 50 EUR that is credited to the ledger of the subscriber.