Beyond is a cloud-based platform that offers a flexible and performant feature set to satisfy the varying requirements of the ecommerce business.
Add new functionality or integrations or build awesome ecommerce applications using our brand new REST API.
Our modern microservice architecture allows you to quickly develop your ecommerce solution by offering you access to services such as checkout, orders, products, payments, and many more.
Anyone who is curious about our new platform can already sign up for a beyondshop.

Use cases

You plan an integration with ePages? That’s great! Here are some use cases we can think of:

Integrate a payment solution

If you have a payment solution in place and would like to integrate with an ecommerce solution, this is where to start.
Check our payment app documentation and find out how to integrate with Beyond!

Terminology

Before we jump right in, let’s look at the key terms that will be used throughout this documentation.

Name

Description

App

The application that would like to interact with the payment gateway, thus integrate with Beyond.

Customer

The visitor of the online shop that is about to purchase products.

JWT

JSON Web Token. According to RFC-7519 a compact, URL-safe means of representing claims to be transferred between two parties.

Merchant

The owner of the online shop that will use your app.

Payment approval page

The page where the customer approves or cancels the payment with your app.

Payment gateway

The Beyond interface to payment apps. Provides an API contract that can be implemented in form of an app in order to integrate a payment with Beyond.

Storefront

The user interface of the customer.

Our requirements

In order to integrate with Beyond, your payment app needs to

communicate with our payment gateway

communicate with your backend

do the data mapping of the single merchant accounts

be run and operated by you, as we currently do not offer to run apps developed by 3rd parties in our system

offer partial refunds if you’d like to offer refunds

There are no further requirements regarding your infrastructure as we are not directly communicating with your backend.
Your backend will only communicate with your app.
Our payment gateway will then forward the requests from the app towards our microservices.
But nevertheless, during the development or the integration of your app, we will stay in close contact.
This way, we can bring certain development steps of your app into our infrastructure and test it.

Authorization

Communication between Beyond API, App, and Merchant

Here’s an overview of what you’ll need to do to communicate with our Beyond API.

Figure 1. Authorisation flow

1. Receive authorisation code

ePages makes a GET request to the Application Callback URL provided by the app developer.
The required query parameters, see table below, will be automatically passed by ePages.

Name

Description

code

Authorisation code that is required for the app installation process to obtain the access_token.

return_url

The URL to which the merchant should be redirected after the app installation.

api_url

The base API URL, that uniquely identifies the merchant. The api_url differs for every merchant and has to be stored in the app.

access_token_url

The URL to obtain the access_token.

signature

The signature is a message authentification code. It is calculated with the code, access_token_url and client_secret.

Although it is optional to validate the signature query parameter, we highly recommend to do so, in order to verify that your request was not changed, and for sure has been provided by ePages and no external, insecure party.
Get in touch with us to get your client_id and client_secret.

2. Registration (optional)

If your app requires a registration process, this optional step can be included before obtaining the access_token.
During this, the app would display the registration or login form to the merchant.

3. Exchange authorisation code for access token

To get an access_token, make a POST request to the token endpoint provided by the access_token query parameter on the Application Callback URL with the following parameters:

Field

Description

code

The code provided in the Application Callback URL.

client_id

The unique identifier for your app.

client_secret

The shared client secret for the app.

Mind the Content-Type! The POST request has to be x-www-form-urlencoded!

In a successful response, a JSON object is returned with the following parameters:

Field

Description

access_token

The encoded JsonWebToken to access the resource.

expires_in

The time of token expiry.

refresh_token

The token that can be used to obtain a renewed access token.

The access_token is a permanent one that can be used to access the shop’s data as long as the app is installed in the merchant’s shop.
This access_token allows your application to act on behalf of the merchant on this specific shop.
Store the access_token, the refresh_token, and the expires in date of the access_token securely against the api_url.

4. Retrieve a shopId

The app additionally needs to store the shopId.
It can be retrieved with the following GET request:

6. Redirect the merchant

Once the authorisation process is complete, your app has to send the merchant back to the return_url the app received before.

Connection to the merchant account

The merchant needs to connect their shop with their payment app account.
That means, that they authorise your app to communicate with your backend on their behalf.
In general, the merchant registers credentials in the app that allow the app to create and update payments on their behalf.
This registration can be implemented in various ways.
We currently only support a referral process for the registration.
In such a referral process the app can use shop data, such as customer address, or email address.
Additionally, the app creates a referralUri to redirect the merchant to a page where they can connect their account.

If you would like to use a different process, get in touch with us.
Otherwise, here’s what you need to do for the referral process:

1. Generate referral URI

In order to initiate a referral process, the app needs to generate the referralUri with a POST request.

The payment gateway will then provide details about the merchant, such as merchant address or email address, as a POST request to the payment app.
This way, the related fields can already be pre-filled and the merchant can register more easily.

Request body properties

Path

Type

Description

shop

Object

A complete shop object. See shops resource for more information.

shopUri

String

The URI of the shop.

redirectUri

String

The URI to which the customer will be redirected after the referral process.

If the response is "ready":true, the referral process was successful and the merchant account is connected with the app.

Payment flow

The payment flow can be triggered in two different steps:

On buy
The payment flow is triggered after the customer selected the button Buy now in the checkout.

On selection
The payment flow is triggered after the customer selected the related payment method in the payment step of the checkout.

It’s up to you to decide which option you would like to choose for your payment app.
The general payment flow stays the same.
Here’s an overview of this general payment flow:

Figure 2. Payment flow

The flow is divided into two main sections:

Creating the payment during the checkout (step 1 & 2 of Fig.2).

Capturing the payment when the order is created (step 3 of Fig.2).

Both of these sections and the related requests are further explained in the following:

1. Create a payment

The customer adds items to their cart, and starts with the checkout.
Depending on the chosen payment flow, a POST request is triggered from the Beyond API to the payment app to create the payment during the checkout process.
In this request, the payment gateway will provide a paymentId as well as related cart and shop information.
As a response to this POST request, the app needs to return an approvalUri.
This approvalUri will then be returned to the storefront.

If the app doesn’t return an approvalUri, an error will be displayed to the customer and they need to choose a different payment method.

2. Approve a payment

When receiving the approvalUri from the Beyond API, the storefront leads the customer to a payment approval page.
On this payment approval page, the customer needs to approve/cancel the payment.
The customer decision is forwarded from the payment approval page to the app.
The app then needs to inform the payment gateway about the decision.
To do so, the payment approval page redirects to an endpoint of the app, which notifies the payment gateway.
Depending on the decision of the customer, either approval or cancelation of the payment, the payment gateway then provides a returnUri.
The payment app needs to respond with a redirect to this URI.

2a. Successful payment

If the app informs the payment gateway that the customer approved the payment, the payment gateway will provide the above-mentioned returnUri to which the customer will be redirected by the app.
In case of an approved payment, the returnUri is the successUri as shown below:

The app then redirects the customer to this URI, e.g. an order success page provided by the payment gateway.

2b. Canceled payment

It is also possible, that a payment is not successful, e.g. if the customer canceled the payment or an error occurred on the app side.
In these cases, the app informs the payment gateway that the payment is canceled.
The payment gateway will then provide a returnUri to which the customer will be redirected by the app.
In case of a canceled payment, the returnUri is the cancelUri as shown below:

The app then redirects the customer to this URI, e.g. back to the last checkout step.

3. Capture a payment

Besides the approval of the customer, the payment needs to be captured.
This capturing is triggered by the payment gateway via a request towards the app.
The payment app needs to response with the current status of the payment.
If the status of the payment is paid, the payment is captured and the payment was successful, as seen in the following POST request:

Set a payment status

In some cases, the payment app might not be able to directly report the status of the payment as paid when the payment is captured.
For example, if the payment request has been accepted but the process in the background is still in progress.
The app then needs to inform the payment gateway about changes of the payment status.
This can be done via a POST request:

Required scopes

paym:m

Request body properties

Path

Type

Description

paymentStatus

String

The status of the payment. Can be one of PENDING, CANCELED, APPROVED, CAPTURED, FAILED, or CAPTURE_PENDING, depending on the former status of the payment.

Carts

The carts resources is used to manage the carts of a shop.
A cart allows customers to pick products from a shop and store them to be bought now or at a later time. The cart can contain a single or various line items. The cart also holds the feature for setting the billing address, the shipping address and shipping zone as well as the payment method.

Delete cart

Create order from cart

A POST request is used to create an order from the cart.

This endpoint can just be used on a cart with checkoutState.readyToOrder == true.
The readyToOrder does not include the availability check, so this might still fail if stock-managed products are not available.

The response contains a location header with a link to the order. Note that the order is created asynchronously and is not available immediately.

Show applicable cart payment method details

A GET request is used to get the applicable payment methods of a cart.
The payment method type is documented here.

The selectable field indicates if a payment method is currently selectable. Non-selectable payment methods
are currently restricted because of rules that apply to a Cart. Trying to set such a payment method as the current one
of the cart will fail.

Indicates if the payment method can be selected for the current cart. A payment method can be become non-selectable if the cart is modified, so that the minimumOrderValue is no longer reached. A cart with an non-selectable payment method cannot be ordered.

_embedded.payment-methods[].lineItemPrice

Object

The calculated price for this payment on the current cart.

_embedded.payment-methods[]._embedded.payment-method._id

String

The immutable, unique identifier of the requested resource.

_embedded.payment-methods[]._embedded.payment-method.position

Number

The sorting position of the payment method in the merchant administration in relation to other payment methods.

_embedded.payment-methods[]._embedded.payment-method.officialName

String

The official name of the payment method chosen by the merchant during setup.

The discount or fee can be an absolute or a percentage based value. Can be one of PERCENTAGE or ABSOLUTE. ABSOLUTE contains another attribute absoluteValue with a positive or negative price. PERCENTAGE contains another attribute percentageValue with a negative or positive percentage value.

The link to trigger the creation of the invoice. This link exists if no invoice has been triggered so far. If the invoice has been created successfully, an invoice-pdf link appears that points to the pdf. If the creation of an invoice has been triggered, but the rendering is not yet finished, a retry-create-invoice link is available.

invoice-pdf

The link to the invoice. This link appears if the invoice has been created successfully.

retry-create-invoice

The link to trigger a retry to create the invoice. This link exists if rendering of the invoice is not yet finished.

send-invoice

The link to trigger the sending of the invoice. This link exists if an invoice-pdf link has been rendered successfully.

right-of-withdrawal-pdf

Optional link to the pdf containing the right of withdrawal applicable for this order.

terms-and-conditions-pdf

Optional link to the pdf containing the terms and conditions applicable for this order.

Show active payment process details

A GET request is used to retrieve the active payment processes.
There is only one active payment process.
See Show payment process details for more information about the request and response structure.

The sorting position of the payment method in the merchant administration in relation to other payment methods.

officialName

String

The official name of the payment method chosen by the merchant during setup.

officialDescription

String

The official description of the payment method chosen by the merchant during setup.

name

String

The name of the payment method that is used during checkout.

description

String

Description of the payment method that is used during checkout.

activated

Boolean

Indicates if a payment method is active. Can be true or false.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

discountOrFee

Object

The details about the fee to be payed or discount to be granted for this payment method.

discountOrFee.type

String

The discount or fee can be an absolute or a percentage based value. Can be one of PERCENTAGE or ABSOLUTE. ABSOLUTE contains another attribute absoluteValue with a positive or negative price. PERCENTAGE contains another attribute percentageValue with a negative or positive percentage value.

serviceableCountries

Array

The list of target countries this payment method can be used in.

minimumOrderValue

Object

The minimum value of the cart so that this payment method can be used.

onlinePayment

Boolean

Indicates if the payment method is an online payment. Can be true or false.

activeLogoSet

Null

The name of the currently selected logo set. Can be TILE, DETAILS, LIST, or STOREFRONT. (official is always the fallback).

Create payment method

The official name of the payment method chosen by the merchant during setup.

Length must be between 0 and 255 inclusive. Must not be empty

officialDescription

String

The official description of the payment method chosen by the merchant during setup.

Length must be between 0 and 4095 inclusive

name

String

The name of the payment method that is used during checkout.

Length must be between 0 and 225 inclusive. Must not be empty

description

String

Description of the payment method that is used during checkout.

Length must be between 0 and 4095 inclusive

discountOrFee

Object

The details about the fee to be payed or discount to be granted for this payment method.

discountOrFee.type

String

The discount or fee can be an absolute or a percentage based value. Can be one of PERCENTAGE or ABSOLUTE. ABSOLUTE contains another attribute absoluteValue with a positive or negative price. PERCENTAGE contains another attribute percentageValue with a negative or positive percentage value.

serviceableCountries

Array

The list of target countries this payment method can be used in.

Each country code must be officially assigned (see ISO 3166-1 Alpha-2)

minimumOrderValue

Object

The minimum value of the cart so that this payment method can be used.

position

Number

The sorting position of the payment method in the merchant administration in relation to other payment methods.

Update payment method

The official name of the payment method chosen by the merchant during setup.

Length must be between 0 and 255 inclusive. Must not be empty

officialDescription

String

The official description of the payment method chosen by the merchant during setup.

Length must be between 0 and 4095 inclusive

name

String

The name of the payment method that is used during checkout.

Length must be between 0 and 225 inclusive. Must not be empty

description

String

Description of the payment method that is used during checkout.

Length must be between 0 and 4095 inclusive

discountOrFee

Object

The details about the fee to be payed or discount to be granted for this payment method.

discountOrFee.type

String

The discount or fee can be an absolute or a percentage based value. Can be one of PERCENTAGE or ABSOLUTE. ABSOLUTE contains another attribute absoluteValue with a positive or negative price. PERCENTAGE contains another attribute percentageValue with a negative or positive percentage value.

serviceableCountries

Array

The list of target countries this payment method can be used in.

Each country code must be officially assigned (see ISO 3166-1 Alpha-2)

minimumOrderValue

Object

The minimum value of the cart so that this payment method can be used.

position

Number

The sorting position of the payment method in the merchant administration in relation to other payment methods.

Indicates if the product is visible in the online shop. Can be true or false.

salesPrice

Object

The reduced price of a product that is currently on offer.

Must match the shop’s tax model. Must not be null

salesPrice.amount

Number

The amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

listPrice

Object

The price of the product without any discounts.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

manufacturerPrice

Object

The manufacturer’s suggested retail price of the product.

manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

manufacturerPrice.taxModel

String

The tax model of the manufacturer’s suggested retail price. Can be GROSS or NET.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

productIdentifiers[].type

String

The product code to identify and classify the product. Can be EAN, UPC, ISBN, or MPN.

productIdentifiers[].value

String

The actual value of the product identifier.

essentialFeatures

String

The essential product properties of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

Must not be null

shippingWeight

Number

The weight of the product including packaging in g.

maxOrderQuantity

Number

Displays how often this product can be ordered at maximum in one order.

shippingPeriod.minDays

Number

The minimum required days for shipping.

shippingPeriod.maxDays

Number

The maximum required days for shipping.

shippingPeriod.displayUnit

String

The unit to show the shipping period. Use DAYS or WEEKS.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice.refQuantity

Number

The reference quantity of the product.

refPrice.quantity

Number

The quantity in the product.

refPrice.unit

String

The unit of the quantity.

refPrice.price

Null

The price information scaled to a standardised base unit, according to the German base price regulation “Preisangabenverordnung” (PAngV), e.g. 1 l = 1.20 EUR. Is null if no reference amount is specified for the product.

Indicates if the product is visible in the online shop. Can be true or false.

salesPrice

Object

The reduced price of a product that is currently on offer.

salesPrice.amount

Number

The amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

listPrice

Object

The price of the product without any discounts.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

manufacturerPrice

Object

The manufacturer’s suggested retail price of the product.

manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

manufacturerPrice.taxModel

String

The tax model of the manufacturer’s suggested retail price. Can be GROSS or NET.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

productIdentifiers[].type

String

The product code to identify and classify the product. Can be EAN, UPC, ISBN, or MPN.

productIdentifiers[].value

String

The actual value of the product identifier.

essentialFeatures

String

The essential product properties of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

shippingWeight

Number

The weight of the product including packaging in g.

maxOrderQuantity

Number

Displays how often this product can be ordered at maximum in one order.

shippingPeriod.minDays

Number

The minimum required days for shipping.

shippingPeriod.maxDays

Null

The maximum required days for shipping.

shippingPeriod.displayUnit

String

The unit to show the shipping period. Use DAYS or WEEKS.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice.refQuantity

Number

The reference quantity of the product.

refPrice.quantity

Number

The quantity in the product.

refPrice.unit

String

The unit of the quantity.

refPrice.price

Object

The price information scaled to a standardised base unit, according to the German base price regulation “Preisangabenverordnung” (PAngV), e.g. 1 l = 1.20 EUR. Is null if no reference amount is specified for the product.

Find existing attribute values

A GET request is used to search for the attribute values that already exist for an attribute name.
This is intended to be able to offer autosuggestion functionality when adding custom attributes to a product.

Required scopes

prod:r

Request parameters

Parameter

Description

namespace

The attribute namespace to search in. If omitted, the namespace 'custom' is used.

attributeName

The attribute name to get values for.

query

The search query. A LIKE query is issued with this query as the search prefix.

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

manufacturerPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

manufacturer

String

The manufacturer of the product.

essentialFeatures

String

The essential features of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

shippingDimension

Object

The shipping dimensions of the product displayed in mm.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

shippingPeriod

Object

The shipping period for this particular product.

attributes[]

Array

The product properties. Identified by a qualified name consisting of namespace and name.

attributes[].namespace

String

The namespace of the product property. Groups all attribute names belonging to the same application in order to prevent name clashes. Example: a SEO app uses the namespace seo, whereas an Enterprise Management System uses ems. Both applications can use the same product property name, e.g. category by using another namespace. Examples: seo:category, ems:category.

attributes[].name

String

The name of the product property.

attributes[].displayName

String

The displayed name of the product property.

attributes[].value

String

The value of the product property.

attributes[].format

Null

The format of the attribute value.

attributes[].formattedValue

String

The formatted value of the product property.

refPrice

Object

The price information scaled to a standardised base unit.

refPrice.refQuantity

Number

The reference quantity the product’s reference price is calculated on.

refPrice.quantity

Number

The actual quantity in the product.

refPrice.unit

String

The unit corresponding to the quanity.

refPrice.price

Object

The actual reference price.

availabilityState

String

The current availability state for the product. Can be IN_STOCK, LOW_STOCK, or OUT_OF_STOCK.

Inventory level that indicates that the product needs to be reordered.

purchasable

Boolean

Indicates if a product can be purchased. Can be true or false.

availabilityState

String

The current availability state of the product. If the related product is not in a purchasable availability state, it will be NOT_AVAILABLE. If the stock level is equal or lower than this value, the availability state is LOW_STOCK. Can be IN_STOCK, LOW_STOCK, NOT_AVAILABLE, or OUT_OF_STOCK.

Custom Product Attributes

The attributes resource is used to manage additional user-defined attributes
on any type supporting this facility.

Attribute types

These are the basic types supported by the API.

Type

Description

BOOLEAN

Boolean value (true,false)

STRING

String value (max. 4kb)

LONG

Long integer

DOUBLE

Double-precision floating number

DATE_TIME

Date and time without timezone information (UTC)

MONEY

Money value

DATA

Byte array

Localization

All attributes can be localized, so that you can assign one specific value per attribute name and locale. If
you want non-localized attributes, just use an empty locale (""), which is equivalent to the "root locale".

Show applicable cart shipping method details

A GET request is used to get the applicable shipping method of a cart.
The shipping method type is documented here

The selectable field indicates if a shipping method is currently selectable. Non-selectable shipping methods are currently restricted because of rules that apply to a cart. Trying to set such a shipping method as the current one of the cart will fail.

Indicates if the shipping method can be selected for the current cart. A shipping method can be become non-selectable if the cart is modified, so that the maximum weight for weight based price is exceeded. A cart with a non-selectable shipping method cannot be ordered.

Sort shipping zones

A PUT request is used to sort the shipping zones.
This is done by passing the self-links of the shipping zones in the desired order.
The request must contain URIs for all shipping zones of the given page.

Sort shipping methods in shipping zone

A PUT request is used to sort the shipping methods inside a shipping zone.
This is done by passing the self-links of the shipping methods in the desired order.
The request must contain URIs for all shipping methods of this shipping zone.

The label of the image that is used to state the purpose of the image. The labels 'logo' and 'fav-icon' can only be assigned once, and have a special meaning. The image with label 'logo' is used as the shop logo. The image with label 'fav-icon' is used as the fav icon of the shop.

Create shop image

Must be a valid storage service URI (must contain a hash query parameter). Must not be null

label

String

The label of the image that is used to state the purpose of the image. The labels 'logo' and 'fav-icon' can only be assigned once, and have a special meaning. The image with label 'logo' is used as the shop logo. The image with label 'fav-icon' is used as the fav icon of the shop.