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

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

Step 1 of 4: Create a charge session

When a customer have 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 details, before returning to the web shop.

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

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

Here is example code in a number of programming languages :

Example 1. cURL

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"
  }'

Example 2. Node

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);
});

Example 3. Ruby

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

Example 4. Python

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

Danger

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.

The call to Billwerk+ Payments's Checkout API will return an object with two parameters.

A charge session id in id
and a payment link in url.

JSON :

{
 "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 :

HTML:

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

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 :

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

Response

JSON :

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

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

Step 4 of 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 :

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: Billwerk+ Payments Checkout.

Types of payment

In this quickstart guide we show a single purchase. But Billwerk+ Payments offers a variety of payment options.

To learn more, please read:

New subscription business
PaymentsPayments

In this section:

Developer Documentation

New web shop

Step 1 of 4: Create a charge session

Note

Warning

Danger

Step 2 of 4: Show customer the payment window

Note

Step 3 of 4: Wait for payment result

Note

Step 4 of 4: Settle charge

Learn more

Payment Window

Types of payment

Search results