Basic concept

Please read this section carefully. It is essential to understand basic concepts and structures to map it to your use case and find a reasonable approach of integration.

You are running a service you want to provide to your customers. The requirements of your customers might be quite different so you defined different sets of features, each set with a specific price. In billwerk these sets are called Plans. These Plans are organized in Plan Groups, Plans, and Plan Variants. During integration most of the time you will just have to deal with Plan Variants. This are the objects customers subscribe to.

When a new customer subscribes to a Plan Variant a successful order process will basically generate a Customer and a Contract. The Customer object contains personal data like name and address. The Contract specifies the subscription details like subscribed plan variant, billing periods, payment bearer, current balance, and others. A customer might want to subscribe to several independent services. Each subscription will be represented by a separate Contract. Unless there is an initial trial period or the customer subscribed to a freemium plan a subscription triggers an immediate billing. Recurring billing processes will then be triggered periodically based on the plan definition. In case of a trial period initial and recurring billing processes will be shifted accordingly.

Within a subscription it might be possible for your customers to order options, add-ons or just use them in a metered fashion. In billwerk these are the so called Components. Component can be ordered with the subscription to a Plan Variant or added/removed independently.
As mentioned there can also be components a customer does not order explicitely and will instead be billed based on Metered Usage. This usage can be passed prior to a billing process.

During lifetime of a subscription it is usually possible for a customer to up- or downgrade to another Plan Variant. During up- or downgrade Components can be added or removed. A Contract keeps a history which is represented by a list of Phases. Each Phase has a start date and usually references a Plan Variant. Up- and downgrading creates a new Phase that references the selected Plan Variant.

Understanding the concept of Phases is essential. There are three types of Phases.

  1. Normal: Defines normal operation. A Plan Variant is referenced, billing is processed based on contract periods
  2. Trial: After subscription a trial period might be granted to the customer. This trial period is represented by a phase of the type "trial".
  3. Inactive: In a phase of this type the subscription is inactive. This can be a pause or regular termination.
A Phase does not have an end date. It is specified by the start date of its successor.

The lifetime of booked Components is handled separately from the contract's phases in Component Subscriptions. Each object represents the subscription to a specific component. It holds data like component reference, contract reference, quantity, start date and an optional end date.

A TaxPolicy basically describes how a certain type of product or services shall be taxed in a given list of countries. For instance, a tax policy's name could be "e-Books" and contain a rule "19%" for Germany and 2.5% for Luxembourg. All products must be mapped to a tax policy through their plan group so billwerk knows which rule to apply when invoicing.

Integrating Billwerk

Sandbox Server

Before we dig into technical detail you can signup up for a free sandbox account -> here <-. The sandbox represents a test system that is completely independent from our live servers. It can be used for any evaluation and integration processes.

Customer Self Service

Primarily, integration means adding billwerk functionality to your customer self service pages.

  1. Public signup / order process: Accessible publicly for new customers
  2. Restricted Customer Portal: Any kind of change for existing customers, be it an upgrade, a cancellation or just the modification of some customer data such as the email address.
There are two approaches to integrate billwerk to your customer self-service: Hosted Pages or a seamless and flexible itegration with BillwerkJS.

Hosted Customer Self-Service

Billwerk provides hosted pages for Signup and Customer Portal. Integration requires little effort and coding skills, but customization is limited.
The Signup can be integrated by a simple redirect. For each signup you'll be notified through a webhook
If you provide a login for your customers integrating the hosted Customer Portal is also done with a simple redirect, although some lines of server side code are required to generate a token that grants timely limited access.

The Hosted Signup Page can be opened with the URL ".../portal/signup.html#/<planVariantId>" where <planVariantId> is the id of the plan variant to be subscribed. If you open the billwerk Admin UI / Products page you will also have direct access to the signup page by clicking the hand symbol at the right side of each plan variant. If you want to prefill customer data you can do so by adding one or more of the following URL parameters:
fname, lname (First- and Last Name)
cname (Company Name)
pnum (Phone Number)
email (Email Address)
street, hnum (Street and House Number)
pcode, city (Postal Code and City)
aline1, aline2 (additional address lines)
country (Country as 2-letter ISO code)
vatid (VAT ID)
tag (A tag field that can be used to pass external id for example)
language (ISO code for languages, which also switches page language between German and English)

Opening the Hosted Portal Page requires requesting an URL with self service access token. Details can be found here. You can also get access to the Hosted Portal of a contract by clicking "Perform Action / Create Self-Service Token" in the Admin UI's contract details.

BillwerkJS

BillwerkJS is a Java Script SDK for seamless integration and full customization of your customer self-service pages (see IWantDonuts.com). The SDK provides a simple, but yet flexible interface to billwerk that covers use cases for signup and customer portal.

In principle, all these actions can be performed via our RESTful JSON API or the management frontend (which directly talks to the API anyhow). However, payment often requires immediate customer interaction (because the payment data is sensitive, or payment requires the customer to visit a page such as PayPal). Also, the goal often is to allow customers to manage their accounts themselves (customer self-service). Hence, we also offer a JavaScript SDK named BillwerkJS that talks to special API endpoints which don't require OAuth authentication.

Hosted Customer Self-Service vs. BillwerkJS

One might be tempted to choose hosted self-service over the BillwerkJS approach. Please ask yourself the following questions. If you answer any of them with "Yes" then BillwerkJS might be the right decision

  • Should billwerk be invisible to my customers?
  • Do I need a custom page layout?
  • Do I want to have full styling freedom?
  • Do I want to add additional form fields for custom data?
  • Do I want to hide specific form fields?
  • Do I want to add custom validation?
  • Do I want to divide the signup process into different steps?
  • Do I need to add custom functionality?

The list could be extended endlessly. You most probably got the point. Requirements for customization are quite individual. Meeting all these requirements in a hosted signup page is almost impossible or would make custom configuration more complex than implementing the self-service yourself in the first place. That's why we came up with BillwerkJS. You get the full flexibility with a simple interface to billwerk.

For a quick start the BillwerkJS documentation also contains code snippets you can use like a construction kit.

No Customer Self-Service required?

If customers sign up with you directly or they don't sign up online at all, for instance if you sell subscriptions via phone or you want to bill existing customers, you can skip integration completely. You can manage subscriptions manually using the billwerk Admin UI. This 'no-self-service' approach is very straightforward if you handle mostly direct debit and invoice payments. If you also want to support credit card, PayPal or Skrill payments, you can still send customers to a page where they can enter their payment information secretly, and without any PCI DSS certification problems. Still, you might want to connect to the API to automatically create customers and contracts in billwerk so they'll be billed automatically.

Synchronization & Reliability

It is essential to keep your system in sync to billwerk, i.e. you must ensure that if your system delivers the bronze plan to a given customer, Billwerk doesn't charge her for platinum. This gives rise to the typical challenges of distributed computing that require a number of approaches to prevent race conditions.

An important concept used both in signups and up/downgrades is that of orders, or more generally speaking, state management on our server. The following example uses our REST API, but the concepts are also true for BillwerkJS. Let's look at how an overly naive implementation of an upgrade could look like:

POST /contracts/:contractId/upgrade
{ "newPlan" : "platinum" }
Such a call comes with a number of problems:
  • It's not reliable. If you don't receive an answer from our server, you don't know the state without inspecting another resource, the contract. Even then, it's possible you wanted to schedule an upgrade in the future so the plan can't have changed yet, hence the state is unknown to you.
  • It's not idempotent.
  • It's not restful.
Instead, the idea is to create, modify and commit orders:
POST /orders/
{ "contractId" : ..., "newPlan" : "" }

// idempotent commit operation
POST /orders/:orderId/commit
This way, you can query the order- or commit- status, because the order has an ID, and the actual operation is idempotent. The details are explained in the section upgrades & downgrades [TBD - we might want to show a long 'recipe' for this that comes with a number of examples].

The same argument applies to signups. If a customer is shown an amount of USD 120,- in step 2 of 3, it is desirable and sometimes required by law to ensure that this is the price that is actually charged when completing the payment. However, because the price could be changed in the mean time and because the price can depend on the checkout time (e.g. a plan that is billed a month in advance but costs per day causes a larger bill in 31-day months than in 30-day months or February), ensuring this on the client is impossible. Therefore, signups internally work by creating a signup order which is committed by the initial payment, or using a separate commit call if no payment is required.

Also, webhooks help to ensure reliablity by repeating requests a large number of times unless they received a response that indicated some kind of success, i.e. a 2xx HTTP status code. Again, this implies that webhook handlers must be idempotent, because it's possible for them to get called multiple times and in incorrect order. Details.

FAQ

How can I customize the self-service pages?
The hosted self-service pages offer little customization, but it's easy to seamlessly integrate all functionality in your frontend using BillwerkJS.
Is it possible to migrate existing customers?
Yes. There are a number of ways to do this (lazy vs. eager), and some details depend on the payment provider(s) you're using. Feel free to contact us to discuss options.
I have a special / complex signup process. Can I implement it in billwerk?
Probably. Flexibility is one of our key goals. Just drop us a line or call us and we can figure something out.
Do we need to worry about PCI DSS compliance?
No, if the form is hosted by us, this does not need to concern you. If you host the form and use BillwerkJS, you'll have to make sure not to send the CC payment information to your server accidentally.
What payment service providers (PSPs) can I choose?
At this time, we support Wirecard, PayOne, Paymill, Heidelpay, Stripe, PayPal and Skrill (Moneybookers). We're adding more PSPs as we go. If you'd like to see your favorite payment provider added, don't hesitate to contact us.
Is it possible to offer multiple payment channels / providers to my customers?
Sure. Just configure the payment providers you want to enable and your customers can choose the one they like best. However, it's not possible to have different providers for a single payment method such as credit card, because it wouldn't be clear which one to use.
Do our customers have to signup with billwerk?
No, they don't have to.