Getting StartedReference Documentation

New subscription business

Suggest Edits

In this scenario you have a business model where customers are billed with regular intervals, e.g. monthly. Reepay Subscriptions is built for this purpose and will automatically deduct the customer.

This quickstart guide will show how quickly you can setup a new subscription business. It is done in three simple steps:

:one: Setup new subscription plan
:two: Create subscription and customer
:three: Get payment information from customer

Step 1 of 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 Reepay administration website. Go to https://admin.reepay.com and select "Configuration" > "Plans" > "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) and a billing cycle (e.g. charge every month). Click the "Create Plan" button and you are all set.

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

Step 2 of 3: Create subscription and customer

The next step is to create a subscription. A subscription ties a subscription plan and a customer. Either a reference to an existing customer can be used, or a new customer can be created when creating the subscription. You can either use the Reepay administration website to create subscriptions or integrate via API calls.

To use the administration website, go to https://admin.reepay.com and select Customers and find customer. You can now click on the customer and select "Add Subscription". Here you can select the subscription plan created in step 1.

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 web site.

Reepay has two models for creating subscriptions:

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

2a Create active subscription

An active subscription can be created in the administration as described above, or using API calls. Here is 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)

See the full documentation for creating subscriptions here: https://reference.reepay.com/api/#create-subscription. 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 Reepay will send a signup email with information on how to set payment information for the subscription.

2b 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 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]"
           }
          }'

See the full documentation for creating a pending subscriptions here: https://reference.reepay.com/api/#prepare-subscription

Notice that as the price of a potential initial invoice can be dependent on the 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.

Step 3 of 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 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. 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 Reepay Checkout API to make a 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 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 and cancel url has been used the customer will be redirected back to one of these. Notice that 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.

🚧

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 https://www.base64encode.org/.

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".

❗️

Keep your private key secret

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

📘

Also remember to replace:
plan-AAAAA with the plan ID from step 1 and
<payment method> with the customer payment method obtained in the previous step.

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

Learn more

Advanced subscription plans

Reepay Subscriptions gives you a lot of flexibility in how you 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 - Reepay Subscriptions handles this automatically and will adjust the next payment depending on when the plan changed.

Combine recurring and one-off payments

Reepay 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 Reepay Token onto your site. This gives you more control over the flow. You can read about custom integration here: Custom Integration

Updated almost 2 years ago