Integrating billwerk
Sandbox Server
Before we dig into technical detail you can signup 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.
Public signup / order process: Accessible publicly for new customers
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: seamless and flexible integration with SubscriptionJS or Hosted Pages.
SubscriptionJS
SubscriptionJS is a JavaScript SDK for seamless integration and full customization of your customer self-service pages. 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). The SDK also provides direct access to account management functions like changing payment data, updating customer information etc. (customer self service).
The SDK also provides an iframe element that serves as a form for the customer to enter payment data. This is especially helpful to minimize your required PCI-DSS compliance (see FAQs below) Future SDK versions will provide additional elements for simpler integration of billwerk.
Thus, implementing customer self-service page with SubscriptionJS offers more possibilities and functions, but at the same time requires more effort from merchant's side.
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:
Parameter | Description |
|---|---|
| First Name |
| Last Name |
| Company Name |
| Phone Number |
| Email Address |
| Street |
| House Number |
| Postal Code |
| City |
| Additional address line |
| Additional address line |
| Country as 2-letter ISO code |
| VAT ID |
| A tag field that can be used to pass an external id for example |
| 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.
Hosted Customer Self-Service vs SubscriptionJS
One might be tempted to choose hosted self-service over the SubscriptionJS approach. Please look at the table below. If want to have any of this features then SubscriptionJS might be the right decision.
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 SubscriptionJS. You get the full flexibility with a simple interface to billwerk.
For a quick start the SubscriptionJS 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.