Documentation

1Overview

This documentation introduces subscriptions and how to set up basic recurring billing for your customers. If you need help after reading this, search our documentation or get in contact to get help setting up the subscriptions.

A detailed API Reference can be found in our API Reference. The API reference links the relevant operations directly with the WebService API Client to send requests directly out of your browser to the web service API.

The idea of the subscription system is to move all the payment and communication between you and your subscriber out of your system. This means we take care of the handling of the scheduling, the upgrades, downgrades and collect the payment information from your subscriber should they be outdated. We only report if a particular subscription should be continued on the merchant side or not. Essentially we send a webhook to the merchant system when the state of the subscription changes. Based up on these state changes the merchant system should activate, pause or terminate the subscription. Anything else is taken care of by us.

2Quick Start

Billing your customers periodically is a common business model, and is easy to do with our platform, requiring only a few steps and knowledge about the general setup:

  1. Create a Charge Flow in order to collect payment informations from your subscribers

  2. Define a product and a product version that defines how much should be billed and when.

  3. Create a subscriber.

  4. Subscribe the subscriber to the previously created product.

Once you have created a product, you only need to execute the second and third steps for every subsequent customer.

3Charge Flows vs. Subscriptions

You can use two different ways to bill a customer for recurring payments. You can either use Charge Flows where the payment is triggered by the merchant or you use the Subscription feature where the calculation of the amounts including the communication etc. is managed by us.

3.1Charge Flows

If you apply a Charge Flow to a transaction object then payment data will be collected according to your charge flow level settings inside your space. In case a customer has a valid token then this will be charged directly. Charge Flows need to be triggered and scheduled by the merchant and therefore should be used in case the merchants wants to control when to charge the client. This is mainly the case for subscriptions involving physical products where you do want to check inventory first. Charge Flows greatly help you to charge your customers as they automatically also handle failure cases and collect missing or wrong payment details from your customer according to your settings.

More information about Charge Flows can be found in the Charge Flow Documentation.

3.2Subscriptions

On the other hand, you want to use the Subscriptions whenever the handling of subscribers, product versions including price calculations etc. should be scheduled by us. In the configuration of the products you define the billing cycle, etc and the platform will automatically handle the collection of payment information and the subsequent charges. The subscriptions feature is also using Charge Flows to charge your subscriber. Compared to the direct use of Charge Flows, the subscription feature organizes also the management of your subscribers, products and calculates the amount that should be charged according to your settings beside the collection of payment information. More information about subscriptions can be found on the following pages.

Note
Due to the fact that the subscription feature also uses Charge Flows to charge the customer, you do also need to activate the Charge Flow Feature and setup at least one charge flow in order to use subscriptions in your space.

4Example

To illustrate the settings below we do use an example subscription product. In the following documentation all settings will be based on this example.

Example

Product Example

We are selling a payment product that has the following specialties:

  • There is a setup fee of 249 EUR for the merchants when signing up.

  • The period fee for the basic payment services are 15 EUR / month

  • Each payment transaction has a price of 10 ct. for the first 1'000 transactions every month. Then we apply a special reduced price.

  • The merchant has the option to subscribe to a special integration service where the product will be installed in his environment.

  • The merchant has the option to subscribe to a special support SLA with specific support hours.

On the future pages we are going to reference this example when we are going to create the product versions, component and component groups.