In this scenario, you have a web shop where customers can buy goods and/or services.

You would like to accept credit cards or other payment methods and for this purpose we provide Billwerk+ Payments Checkout.

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

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

1️⃣/4️⃣ Create a charge session

When a customer has filled items in the shopping basket on your site and clicks “Buy”, you need to create a new Billwerk+ Payments 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 needs to be placed on your server. This is to avoid tampering where the customer can edit the price directly in the browser.

📘

Note

This example shows the fastest way to be ready to accept payments:

The customer is redirected to a standalone browser window to enter credit card detils, before returning to the web shop.

For this the two parameters accept_url and cancel_url have to be provided.

🚧

Warning

The payment window can also be integrated directly on your web page. For a walk-through of the possibilities, click here - Billwerk+ Checkout.

---

Here is an 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":10000,
         "currency":"DKK",
         "customer": {
             "email":"[email protected]",
             "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":10000,
     "currency":"DKK",
     "customer":
        {
         "email":"[email protected]",
         "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\":10000,\"currency\":\"DKK\",\"customer\":{\"email\":\"[email protected]\",\"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\":10000,\"currency\":\"DKK\",\"customer\":{\"email\":\"[email protected]\",\"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)

The Billwerk+ Optimize Checkout Helper can be used to learn more about the API and to construct Checkout API calls.

🚧

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.

The call to Billwerk+ Optimize'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"
}

2️⃣/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 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_22222222222222222222222222222222');
</script>

📘

Note

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.

3️⃣/4️⃣ Wait for payment result

Depending on whether 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 checking 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 has an attribute state that can be used to determine if the charge was successful. If 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 a receipt page or the like.

📘

Note

Webhooks

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

In this case you will have to listen for invoice_authorized and invoice_settled events. For more information on webhooks see Webhooks.

4️⃣/4️⃣ Settle charge

Usually, a payment is divided into two.

• Authorization · The payment method of the customer is verified, and the amount is reserved.
• 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 quick start 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: Billwerk+ Checkout.

Types of payment

In this quick start guide, we show a single purchase. But Billwerk+ Optimize offers a variety of payment options.