In this scenario your business is based on a model, where customers are billed with regular intervals, e.g. monthly. Billwerk+ Optimize is built for this purpose and will automatically deduct the customer.

This quick start guide will show how quickly you can set up a new subscription business. It is done in three simple steps:

Setup new subscription plan
Create subscription and customer
Get payment information from customer

1️⃣/3️⃣ Setup new subscription plan

A subscription plan defines a subscription product: how much should a subscription cost, how often should the customers be deducted, etc.

You can create a plan in the Billwerk+ Optimize administration interface.

Go to the admin UI
Navigate to Configuration > Plans
Click on New to create a new plan
For now, we will create a simple plan:
- Enter a name for the subscription plan (e.g. "Gold subscription")
- Enter a price (e.g. 100kr)
- Set a billing cycle (e.g. charge every month)
Click on Create and you are all set

🚧
Important
Note down the Plan ID as we will need it in step 3 when creating a subscription.

2️⃣/3️⃣ Create subscription and customer

The next step is to create a subscription. A subscription ties a subscription plan and a customer:

A reference to an existing customer can be used
or a new customer can be created when creating the subscription.

There are two options (A or B) to create subscriptions:

🅰️ Use either the Billwerk+ Optimize administration website to do it manually:

Go to the admin UI
Navigate to Customers and click on the relevant customer entry in the table
Click on Create Subscription, then choose the plan you created earlier.

For more detailed information, please read this article.

🅱️ or integrate them via API calls:

If you instead wish to integrate directly with your system, you can do so using API calls. This allows you to seamlessly integrate the subscription into your website.

Please find more information about the endpoint in our API documentation.

Billwerk+ Optimize has two models for creating subscriptions:

Create an immediate active subscription and subsequently get payment information from the customer.
Create a pending subscription that is activated once the customer enters payment information.

2️⃣.1️⃣ Create active subscription

An active subscription can be created in the administration as described above, or using API calls.

Here is an example code in a number of languages:

curl --request POST \
  --url https://api.reepay.com/v1/subscription \
  --header 'Accept: application/json' \
  -u 'priv_11111111111111111111111111111111:' \
  --header 'Content-Type: application/json' \
  --data '{"plan":"plan-AAAAA",
           "handle": "subscription-101",
           "create_customer": {
              "handle": "customer-007",
              "email": "[email protected]"
           },
           "signup_method":"link"}'

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.reepay.com/v1/subscription',
  headers: 
   { authorization: 'Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo=',
     'content-type': 'application/json',
     accept: 'application/json' },
  body: '{"plan":"plan-AAAAA","customer":"customer-2","handle":"s-101","signup_method":"link"}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.reepay.com/v1/subscription")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request["authorization"] = 'Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo='
request.body = "{\"plan\":\"plan-AAAAA\",\"customer\":\"customer-2\",\"handle\":\"s-101\",\"signup_method\":\"link\"}"

response = http.request(request)
puts response.read_body

var data = "{\"plan\":\"plan-AAAAA\",\"customer\":\"customer-2\",\"handle\":\"s-101\",\"signup_method\":\"link\"}";

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.reepay.com/v1/subscription");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo=");

xhr.send(data);

import requests

url = "https://api.reepay.com/v1/subscription"

payload = "{\"plan\":\"plan-AAAAA\",\"customer\":\"customer-2\",\"handle\":\"s-101\",\"signup_method\":\"link\"}"
headers = {
    'accept': "application/json",
    'content-type': "application/json",
    'authorization': "Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo="
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Please see the full API documentation for creating subscriptions here: Create subscription.

📘
Note
Notice the argument signup_method.
In the example link is used to indicate that payment information will be obtained using a Checkout Subscription session.
It is also possible to use email as signup method. In this case Billwerk+ will send a signup email with information on how to set payment information for the subscription.

2️⃣.2️⃣ Create pending subscription

If the subscription should only be active when the customer enters valid payment information, a pending subscription can be created. A pending subscription is like a template for a subscription waiting to be activated.

Use this approach if you do not want to start billing the customer until payment information has been obtained.

Here is an example code:

curl --request POST \
  --url https://api.reepay.com/v1/subscription/prepare \
  --header 'Accept: application/json' \
  -u 'priv_11111111111111111111111111111111:' \
  --header 'Content-Type: application/json' \
  --data '{"plan":"plan-AAAAA",
           "handle": "subscription-101",
           "create_customer": {
              "handle": "customer-007",
              "email": "[email protected]"
           }
          }'

📘
Note

As the price of a potential initial invoice can depend on the time, when a subscription is created, e.g. prorated billing,

and that the price needs to be known, when the customer enters payment information, as the initial invoice will be attempted paid, the billing dates will be set from the time the pending subscription was created.

See the full API documentation for creating pending subscriptions here: Prepare Subscription.

3️⃣/3️⃣ Get customer payment information

The simplest way to get customer payment information is to use the link provided in the subscription object:

"hosted_page_links": {
	"payment_info": "https://checkout.reepay.com/#/subscription/pay/da_DK/.../..."
}

The link will start a subscription session, where the customer can attach payment information to the subscription.

If the subscription is pending: it will be activated when valid payment information has been entered.
If the subscription has an initial invoice: it will be paid before using the payment information for the subscription.

The link can be sent to the customer on mail, or the customer can be redirected to the link.

📘
Note
This simple approach has limited integration possibilities. To get full control of the process a subscription session can be created as described in the below steps.

3️⃣.1️⃣ Create a subscription session

Use the Billwerk+ Checkout API to create subscription session for the subscription.

curl --request POST \
  --url https://checkout-api.reepay.com/v1/session/subscription \
  -u '<your private key>:' \
  --header 'content-type: application/json' \
  --data '{
    "button_text":"Signup",
    "subscription": "subscription-101",
    "accept_url": "https://mysystem.com/accept",
    "cancel_url": "https://mysystem.com/cancel"
  }'

Response:

{
  "id": "cs_5fb7cc4e5c7ed6629c6c8b16d91683aa",
  "url": "https://checkout.reepay.com/#/subscription/cs_5fb7cc4e5c7ed6629c6c8b16d91683aa"
}

3️⃣.2️⃣ Include the Checkout Web SDK

Read more about different ways to use Checkout.

<script src="https://checkout.reepay.com/checkout.js"></script>

3️⃣.3️⃣ Show the customer the signup window

In order to integrate the payment window in your web shop, you will need to add a few lines of code to your web page.

Here is an example code to include in your HTML file:

<script src="https://checkout.reepay.com/checkout.js"></script>
<script>
  var rp = new Reepay.WindowCheckout('cs_5fb7cc4e5c7ed6629c6c8b16d91683aa');
</script>

3️⃣.4️⃣ Show a receipt page

If the accept url and cancel url have been used, the customer will be redirected back to one of these.

📘
Note
The customer might close the browser before reaching the return url, or there might be a connection problem, so we recommend to also listen for webhooks if you need to update state on your side.

🚧
Warning
HTTP Basic Authentication
The private API key must be provided as the HTTP Basic Auth username. Remember a colon : after the private API key. The colon separates username and password in HTTP Basic Auth. In this case the password is empty.
The basic authentication needs to be base64 encoded before submitting. Some coding frameworks will do this for you, but most commonly you need to do the encoding. You can base64 encode online using this link.
Example
The private API key is :
priv_11111111111111111111111111111111\.
This is encoded as:
base64(priv_11111111111111111111111111111111:) = cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo=\
(notice the : after the API key)
The full HTTP header will be:
Authorization: Basic
cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo=
Replace priv_11111111111111111111111111111111 with your own API key, which you can find at https://admin.reepay.com under Developers > API Credentials.

❗️
Danger
Keep your private key secret
Your private API keys carry many privileges, so be sure to keep them secret! Only ust the private key in server-to-server API calls, never from the frontend, as that will expose the private key to anybody.

📘
Note
Please remember to replace
plan-AAAAA with the plan ID from step 1 with the customer payment method obtained in the previous step.

👍
Success!
You have now successfully created a subscription, which automatically will be deducted each month.

📙 Learn more

Advanced subscription plans

Billwerk+ Subscription Management (Lite/ Expert) gives you a lot of flexibility on how to model your subscriptions. For a more information about the different tools, click here: Subscriptions.

Automatic handling of change of subscription plan

What if the customer changes or cancels the subscription plan in the middle of a subscription period? No problem - Billwerk+ Optimize handles this automatically and will adjust the next payment depending on when the plan changed.

Combine recurring and one-off payments

Billwerk+ Optimize fully supports mixing recurring payments and one-off payments. You may have a fixed monthly fee, but allow the user to purchase goods and/or services in a web shop. By having the customer store his card as a reusable payment method, the same payment information can be used for one-off payments, so the user will not to enter all payment details again. To learn more, read here: Payments.

Another example is the combination of a one-off payment with a subscription signup or save of customer payment method for later use. For more information, see Mixing products.

Dunning

A payment can fail for a number of different reasons. A dunning plan gives you an automated way of dealing with this situation. Read more about Dunning plans here: Dunning plan.

Advanced integration

You can integrate directly to our API if you need more advanced functionality. Read more about our API-first approach.

Also, we allow for custom integration of Billwerk+ Optimize Token onto your site. This gives you more control over the flow.

New subscription business

1️⃣/3️⃣ Setup new subscription plan

🚧
Important

2️⃣/3️⃣ Create subscription and customer

2️⃣.1️⃣ Create active subscription

📘
Note

2️⃣.2️⃣ Create pending subscription

📘
Note

3️⃣/3️⃣ Get customer payment information

📘
Note

3️⃣.1️⃣ Create a subscription session

3️⃣.2️⃣ Include the Checkout Web SDK

3️⃣.3️⃣ Show the customer the signup window

3️⃣.4️⃣ Show a receipt page

📘
Note

🚧
Warning

HTTP Basic Authentication

Example

❗️
Danger

Keep your private key secret

📘
Note

👍
Success!

📙 Learn more

Advanced subscription plans

Automatic handling of change of subscription plan

Combine recurring and one-off payments

Dunning

Advanced integration

1️⃣/3️⃣ Setup new subscription plan

🚧Important

2️⃣/3️⃣ Create subscription and customer

2️⃣.1️⃣ Create active subscription

📘Note

2️⃣.2️⃣ Create pending subscription

📘Note

3️⃣/3️⃣ Get customer payment information

📘Note

3️⃣.1️⃣ Create a subscription session

3️⃣.2️⃣ Include the Checkout Web SDK

3️⃣.3️⃣ Show the customer the signup window

3️⃣.4️⃣ Show a receipt page

📘Note

🚧Warning

HTTP Basic Authentication

Example

❗️Danger

Keep your private key secret

📘Note

👍Success!

📙 Learn more

Advanced subscription plans

Automatic handling of change of subscription plan

Combine recurring and one-off payments

Dunning

Advanced integration

🚧
Important

📘
Note

📘
Note

📘
Note

📘
Note

🚧
Warning

❗️
Danger

📘
Note

👍
Success!