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 web shop

In this scenario you have a web shop where customers can buy goods and/or services. You would like to accept credit card or other payment methods and for this purpose we provide Reepay Checkout.

To integrate Reepay Checkout in your web shop there are four steps:

  1. Create a charge session
  2. Show customer the payment window
  3. Wait for payment result
  4. Settle charge if not instant settle

Step 1 of 4: Create a charge session

When the customer have filled items in the shopping basket on your site and click "Buy", you need to create a new Reepay Checkout charge session for a single payment.

A charge session contains all payment information about the purchase: amount, currency, order number, etc.

The code to generate the payment session should be placed on your server. This is to avoid tampering where the customer can edit the price directly in the browser.

This example shows the fastest way to be ready to accept payments. Here the customer is redirected to a standalone browser window to enter credit card details, before returning to the web shop. For this the two parameters accept_url and cancel_url should be provided. The payment window can also be integrated directly on your web page. For a walk-through of the possibilities click here: Reepay Checkout.

Here is example code in a number of programming languages:

curl -X POST \
  --url https://checkout-api.reepay.com/v1/session/charge \
  --header 'Accept: application/json' \
  -u 'priv_11111111111111111111111111111111:' \
  --header 'Content-Type: application/json' \
  --data '{
    "order": {
         "handle":"order-12345",
         "amount":100,
         "currency":"DKK",
         "customer": {
             "email":"johndoe@somedomain.com",
             "handle":"c-0212",
             "first_name":"John",
             "last_name":"Doe"
         }
    },
    "accept_url":"https://webshop.com/accept/order-12345",
    "cancel_url":"https://webshop.com/decline/order-12345"
  }'
var request = require("request");

var options = { method: 'POST',
  url: 'https://checkout-api.reepay.com/v1/session/charge',
  headers: 
   { authorization: 'Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo=',
     'content-type': 'application/json',
     accept: 'application/json' },
  body: '{"order":{"handle":"order-12345","amount":100,"currency":"DKK","customer":{"email":"johndoe@somedomain.com","handle":"c-0212","first_name":"John","last_name":"Doe"}},"accept_url":"https://webshop.com/accept/order-12345","cancel_url":"https://webshop.com/decline/order-12345"}' };

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

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://checkout-api.reepay.com/v1/session/charge")

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 = "{\"order\":{\"handle\":\"order-12345\",\"amount\":100,\"currency\":\"DKK\",\"customer\":{\"email\":\"johndoe@somedomain.com\",\"handle\":\"c-0212\",\"first_name\":\"John\",\"last_name\":\"Doe\"}},\"accept_url\":\"https://webshop.com/accept/order-12345\",\"cancel_url\":\"https://webshop.com/decline/order-12345\"}"

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

url = "https://checkout-api.reepay.com/v1/session/charge"

payload = "{\"order\":{\"handle\":\"order-12345\",\"amount\":100,\"currency\":\"DKK\",\"customer\":{\"email\":\"johndoe@somedomain.com\",\"handle\":\"c-0212\",\"first_name\":\"John\",\"last_name\":\"Doe\"}},\"accept_url\":\"https://webshop.com/accept/order-12345\",\"cancel_url\":\"https://webshop.com/decline/order-12345\"}"
headers = {
    'accept': "application/json",
    'content-type': "application/json",
    'authorization': "Basic cHJpdl8xMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTo="
    }

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

print(response.text)

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

The call to Reepay's Checkout API will return an object with two parameters. A charge session id in id and a payment link in url.

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

Step 2 of 4: Show customer the payment 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_22222222222222222222222222222222');
</script>

Replace cs_22222222222222222222222222222222 with the payment session id obtained in the previous step.

The code shown above will automatically redirect the user to the payment window. Here the customer can enter his payment details.

Step 3 of 4: Wait for payment result

Depending on whether or not the payment is successful the user is then directed back to the accept_url or cancel_url provided in the previous step. The order handle and customer reference are provided on the url as query parameters. The return url can be tampered with, we therefore highly recommend to check the actual status of the charge with at server-to-server API call when the customer returns.

curl -X GET \
    --url https://api.reepay.com/v1/charge/order-12345 \
    -u 'priv_11111111111111111111111111111111:' \
    -H 'Accept: application/json'

Response

{
    "handle": "order-12345",
    "state": "authorized",
    ...
}

For details see Get Charge.

The Charge object returned has an attribute state that can be used to determine if the charge was successful. If the the state is authorized or settled, depending on whether instant settle was requested, the charge was successful.

On a successful charge your order entry can be updated and the customer can be presented with receipt page or the like.

To make sure that a successful payment reaches your site, we highly recommend using webhooks. Webhooks are fired asynchronously and retried until they are successfully received at your site. Webhook urls can be configured in the administration admin.reepay.com. In this case you will have to listen for invoice_authorized and invoice_settled events. For more information on webhooks see Webhooks

Step 4 of 4: Settle charge

Usually a payment is divided into two.

  1. Authorization – The payment method of the customer is verified, and the amount is reserved.
  2. Settle - The reserved amount is transferred from customer to your account. Also called a capture.

The normal scenario is the ordering of some goods. The amount is authorized when the order is placed, and the payment is settled when the goods are shipped. An authorization is usually valid for seven days. To settle an authorized charge use the following call:

curl -X POST \
    --url https://api.reepay.com/v1/charge/order-12345/settle \
    -u 'priv_11111111111111111111111111111111:' \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json'

The charge object is returned and state must be settled for the operation to be successful. For details and additional options see Settle Charge.

Learn more

Payment Window

This quickstart guide shows the fastest way to be ready to accept payments. Here the customer is redirected to a new page to enter credit card details, before returning to the web shop.

But you can customize the payment window in a variety of ways and integrate the payment directly on your web page. For a walk-through of the possibilities click here: Reepay Checkout

Types of payment

In this quickstart guide we show a single purchase. But Reepay offers a variety of payments option. To learn more see New subscription business and Payments

New web shop


Suggested Edits are limited on API Reference Pages

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