Reepay Technical Documentation

Hello Developer!

Welcome to the Reepay API developer hub. You'll find comprehensive guides and documentation to help you get started working with the Reepay API as quickly as possible, as well as support you if your stuck.

Let's jump right in!

Get Started

New subscription business

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 customer & get payment information
:three: Create subscription

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 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 customer & get payment information

Use Reepay Checkout to create a customer and store the customers card. For an introduction see Reepay Checkout.

2.1 Create a recurring session

Use the Reepay Checkout API to make a recurring session for the customer "Spongebob". The handle customer-2 is the customer id from own system. If the customer already exists the the existing customer will be used with the customer information already at Reepay.

curl --request POST \
  --url \
  -u '<your private key>:' \
  --header 'content-type: application/json' \
  --data '{
        "email":"[email protected]",
        "address":"124 Conch Street",
        "address2":"Bikini Bottom",
        "city":"Pacific Ocean",



2.2 Include the Checkout Web SDK

Read more about different ways to use Checkout

<script src=""></script>

2.3 Open the window as overlay (modal)

var rp = new Reepay.ModalCheckout(' YOUR SESSION ID HERE ');

rp.addEventHandler(Reepay.Event.Accept, function(data) {
  console.log('Success', data);
  // The customer handle will be in this
  // The customers payment information will be in this

Step 3 of 3: Create subscription

You can either use the Reepay administration website to create subscriptions or integrate via API calls.

To use the administration website, go to 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. Here is example code in a number of languages:

curl --request POST \
  --url \
  --header 'Accept: application/json' \
  -u 'priv_11111111111111111111111111111111:' \
  --header 'Content-Type: application/json' \
  --data '{"plan":"plan-AAAAA",
           "handle": "s-101",
           "customer": "customer-2",
var request = require("request");

var options = { method: 'POST',
  url: '',
   { authorization: 'Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo=',
     'content-type': 'application/json',
     accept: 'application/json' },
  body: '{"plan":"plan-AAAAA","source":"<payment_method>","customer":"customer-2","handle":"s-101","signup_method":"source"}' };

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

require 'uri'
require 'net/http'

url = URI("")

http =, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request =
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request["authorization"] = 'Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo='
request.body = "{\"plan\":\"plan-AAAAA\",\"source\":\"<payment method>\",\"customer\":\"customer-2\",\"handle\":\"s-101\",\"signup_method\":\"source\"}"

response = http.request(request)
puts response.read_body
var data = "{\"plan\":\"plan-AAAAA\",\"source\":\"<payment method>\",\"customer\":\"customer-2\",\"handle\":\"s-101\",\"signup_method\":\"source\"}";

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
});"POST", "");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo=");

import requests

url = ""

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

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



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

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


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 2 months ago

New subscription business

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.