Integration Guide for Orders (Smart Checkout / JavaScript)

Introduction

Smart Checkout extends the payment service by a complete checkout and further order processing tools. This saves the merchant the implementation of the complex checkout process. The Checkout Wizard by secupay will request delivery information and payment details from the customer. After final confirmation, the merchant receives a complete order, ready for delivery. He can use SecuOffice for further order processing such as shipment or collection.

This guide will show you how to integrate the Checkout Wizard into your website or e-commerce system using JavaScript. This integration method is recommended for websites and small online shops that sell articles from only one merchant. If you want to use Smart Checkout in a marketplace scenario, you need another intergration method and guide.

Security notice

With this integration method, the basket is passed to the Checkout Wizard using means of JavaScript. This bears a risk of manipulation of the basket in the browser. The merchant is therefore obligated to check incoming orders before processing. Please refer to our Terms and Conditions for details. For added security, please consider preparing Smart Transactions that include the basket, using our secuconnect API. This way, you can verify the basket on your servers. You can find integration guides for API-based integration methods as well.

The integration guide begins with a Getting Started section, that explains the basic concepts and important key terms. In this section, you will learn how to create a first order and start the Checkout Wizard. We recommend to study the Getting Started section thoroughly. The remaining sections, Reference and Troubleshooting, can be accessed when needed. Should you require assistance with integration or further order processing, our support staff will be happy to help.

Getting Started

This section demonstrates how to integrate the Checkout Wizard in a very a simple shop page. You should have basic knowledge of HTML and JavaScript in order to follow and use the integration.

First you will learn a few basic key terms. Then we start integration step by step with a working example that can be integrated in your application with a few adjustments . Finally we will explain the example in detail before, in the Reference section we show what additional options are available to adjust the checkout to your needs.

Key Terms

Merchant and Contract

The merchant sells products to the customer or offers a service. Thus he delivers something and receives the payment for it. As payment service provider (PSP), secupay cares for the payment and interacts with both, the merchant and his customer.

Every merchant can have one or more contracts with secupay for different purposes. These contracts are managed behind the scenes for you. Important for you: Yuo will receive one or more contract IDs (GCR_xxx), and some information for which purpose you shall use them.

Smart Transaction and Payment Transaction

A Payment Transaction manages the payment process between secupay and your customer as well as between secupay and you, the merchant. It is defined by the payer and the payee, the payment method and the amount.

A Smart Transaction is rather a business transaction like a purchase order. It knows about the status of the payment, and manages delivery and the like. The Payment Transaction is managed by the Smart Transaction, and associated to it.

Checkout Workflow

Using JavaScript integration, this is the standard checkout flow:

  1. The customer selects goods in the merchant's shop, and starts the checkout.

  2. The merchant's shop adds the goods to a basket managed by secupay's JavaScript integration code.

  3. To start the checkout, the merchant's shop calls the JavaScript integration code by secupay .

  4. The customer checks out using the Checkout Wizard by secupay.

  5. The Checkout Wizard directs the customer to a success URL of the merchant's shop.

When all steps of the process are completed successfully, the Smart Transaction is waiting for a pending payment, or even ready for delivery. It is not guaranteed that the customer opens the offered success URL.

If the customer aborts the checkout, they are directed to the abort URL, if defined. It is not guaranteed that the customer opens the offered URL. They can also simply stop to interact with the browser or close the browser window.

Working Example

We begin with a very simple shop page:

<!DOCTYPE html>
<html>
<head>
<title>JavaScript Integration Demo</title>
<meta charset="utf-8"/>
</head>
<body>
<h1>JavaScript Integration Demo</h1>
<p>
Our button to check out will appear here.
</p>
</body>
</html>

This is just enough to show an empty page with a headline. In order to integrate with the Checkout Wizard we need to include a CSS and a JavaScript file, set the contract ID, and finally set the basket and start the checkout.

Step 1: Include CSS and JavaScript

This code integrates the JavaScript and the CSS in the <head> section of your HTML document:

<head>
...
<link rel="stylesheet" type="text/css" href="https://checkout.secupay.com/assets/css/secupay-checkout.css">
<script type="text/javascript" src="https://checkout.secupay.com/assets/js/secupay-checkout.js"></script>
</head>

Surely your page will also have their own CSS and JavaScript. Best you add our CSS after yours, and our JavaScript after your JavaScript files.

Step 2: Set the contract ID

Now we set the contract ID. It only needs to be set once.

<head>
<!-- ... -->
<script type="text/javascript">
secupayCheckout.setOptions({
contractId: "GCR_WA66JUP62PNVHBHCXA57PRUNKZP0P5",
isDemo: true
});
</script>
</head>

Since you use call a function provided in our JavaScript file, this must follow the other <script> tag.

Later you need to set your real contract ID, so that the orders are associated with you the right contract.

Step 3: Set the basket and start the checkout

Finally we extend our script section with a callback handler and to wire it with a button.

We can define the handler in the same <script> section with the contract ID:

<script type="text/javascript">
secupayCheckout.setOptions({ contractId: "GCR_WA66JUP62PNVHBHCXA57PRUNKZP0P5" });
function buttonHandler() {
secupayCheckout.setBasket([
{
name: "ACME ball pen Modern Line 8050",
price: 1595,
quantity: 1,
tax: 19
},
{
name: "ACME pen case Modern Line",
price: 1795,
quantity: 1,
tax: 19
}
]);
secupayCheckout.enterCheckout();
}
</script>

Our callback handler sets a basket with two elements. After this is done, it starts the checkout.

And this is our button:

<button type="button" onclick="buttonHandler();">Check out with pen + case ...</button>

The final result looks like this:

<!DOCTYPE html>
<html>
<head>
<title>JavaScript Integration Demo</title>
<meta charset="utf-8"/>
<link rel="stylesheet" type="text/css" href="https://checkout.secupay.com/assets/css/secupay-checkout.css">
<script type="text/javascript" src="https://checkout.secupay.com/assets/js/secupay-checkout.js">
</script>
<script type="text/javascript">
secupayCheckout.setOptions({
contractId: "GCR_WA66JUP62PNVHBHCXA57PRUNKZP0P5",
isDemo: true
});
function buttonHandler() {
secupayCheckout.setBasket([
{
name: "ACME ball pen Modern Line 8050",
price: 1595,
quantity: 1,
tax: 19
},
{
name: "ACME pen case Modern Line",
price: 1795,
quantity: 1,
tax: 19
}
]);
secupayCheckout.enterCheckout();
}
</script>
</head>
<body>
<h1>JavaScript Integration Demo</h1>
<p>
<button type="button" onclick="buttonHandler();">Check out with pen + case ...</button>
</p>
</body>
</html>

Here you see the page:

images/plugins/servlet/confluence/placeholder/unknown-attachment.png

And this happens, when we press the button:

images/plugins/servlet/confluence/placeholder/unknown-attachment.png

Of course, later you will set the basket more dynamically. You might also use different controls to add articles to the basket and to start the checkout process.

Summary

You have seen how to integrate our Checkout Wizard with your website using JavaScript. We let the website prepare a purchase order, assisted by the integration code provided by secupay.

Additionally you can:

  • Pass more details to basket items, like a EAN/GTIN or an article number/SKU number of your own.

  • Pass stakeholder shares, for instance to pay out sales provisions

  • Define static or individual URLs to direct the customer back to your page after successful or failed checkout

  • Change the default language of the Checkout Wizard

Most of the mentioned things are described in the reference below. If you don't find the needed information, please do not hesitate to ask us.

Reference

Global Options

You can set all global options using secupayCheckout.setOptions(options).

The only mandatory option is the contract ID of the merchant. Further you can set:

  • demo mode for test orders;

  • URLs to direct the customer back to the shop after successful checkout;

  • the language the Checkout Wizard shall show on start;

  • the view mode of the Checkout Wizard.

A complete example:

secupayCheckout.setOptions({
contractId: "GCR_xxx",
isDemo: true,
purpose: "123",
merchantUrls: {
url_success: "https://shop.example.org/success?a=123",
url_failure: "https://shop.example.org/failure?b=123"
},
lang: "de",
urlParams: {
viewMode: "fullscreen",
initPaymentMethod: "Debit"
},
});

Detailed description of the object attributes:

Attribute

Type

Description

contractId

string

Contract ID of the merchant

Note: Please do not forget to replace the contract ID in the above example with your real contract ID, assigned during the onboarding process.

intent

string

You can decide about the order processing offered after closure using the intent. The intents for checkout are:

  • checkout: The Checkout Wizard negotiates all the needed details with the customer. After this you find the order either ready for delivery or waiting for a pending payment. But once the payment is approved, the further process is up to you. (There is one exception: We need to be informed about the delivery of orders with invoice payments. The due date depends on it.)

  • order: SecuOffice also helps you with order processing.

If the flag is not present, it defaults to order.

isDemo

boolean

Optional flag to designate demo or test orders:

  • true for demo/test orders;

  • false for real orders.

If the flag is not present, it defaults to false for a real order.

The payment for demo/test orders is not processed. Demo orders cannot be changed into productive ones, but productive ones can be cancelled.

Demo transactions are also marked in SecuOffice.

Note: Please do not forget to switch this flag properly.

purpose

string

Optional line of text. It is the purpose that appears on the bank statements of the customer, and on the advice note of the merchant. This works only with intent sale and authorization, but is likely to be changed.

merchantUrls.url_success

string

Optional http: or https: URL to direct the user back to the shop after the order was placed successfully.

If not present, the static succuess URL is used, that was defined in SecuOffice. If not defined either, there is no back link in this situation.

merchantUrls.url_failure

string

Optional http: or https: URL to direct the user back to the shop after the user stopped the checkout explicitly, or in case of a technical problem.

If not present, the static failure URL is used, that was defined in SecuOffice. If not defined either, there is no back link in these situations.

lang

string

Optional. Initial language of the Checkout Wizard:

  • "de" to start in German;

  • "en" to start in English.

If this setting is not present, it defaults to German.

urlParams.viewMode

string

Optional switch from layer to fullscreen mode:

  • "layer" starts the Checkout Wizard in a modal layer above the shop;

  • "fullscreen" starts the Checkout Wizard fullscreen, replacing the shop.

Note: In some browsers it is not possible to start the Checkout Wizard in a modal layer due to restrictive implementations of Cross-Origin Ressource Sharing (CORS). Also some particular workflows can force the browser to switch to fullscreen mode, and replace to shop page. So we recommend you to test your integration, whether it would work in fullscreen mode too.

If this setting is not present, it defaults to the modal layer.

urlParams.initPaymentMethod

string

Optional payment method for sale or authorization:

  • Debit for SEPA direct debit;

  • Creditcard;

  • Invoice;

  • Prepaid for advance payment.

If you don't pass a payment method, the customer can choose of all available payment methods.

Basket Management

You can set the basket items using secupayCheckout.setBasket(items). The parameter items is an array of JavaScript objects, each element representing a basket item.

Each item is a JavaScript object, and needs to have these properties:

  • quantity;

  • article name;

  • gross unit price;

  • VAT rate.

Additionally, you can also pass:

  • your article number, or storage keeping unit (SKU);

  • the official EAN (or GTIN) of this product.

Full example:

secupayCheckout.setBasket([
{
id: 1,
quantity: 1,
name: "ACME ball pen Modern Line 8050",
articleNumber: "ACM/BPMOD-8050",
ean: "4001234567893",
price: 1595,
tax: 19
},
{
id: 2,
quantity: 1,
name: "ACME pen case Modern Line",
articleNumber: "ACM/CASMOD",
ean: "4002345678907",
price: 1795,
tax: 19
}
]);

The gross unit price is the price for one unit, including the value added tax (VAT). It is expressed in the smallest currency unit. In our example it is €15,95, or €17,95 respectively.

Detailed description of the objects for the basket items:

Attribute

Type

Description

id

bigint

Optional. Item ID to manage the item later.

quantity

bigint

The amount as integer.

articleNumber

string

Optional. Your internal article number, or storage keeping unit (SKU).

ean

string

Optional. The official EAN or GTIN of this product.

Note: If your product has no EAN or GTIN, please omit this attribute. It might conflict with real GTINs that need to be evaluated by use. We need to evaluate EANs when you start a loyalty card programme to detect loyalty cards, or articles with special tax handling. We also need to evaluate EANs when you start to sell e-goods, phone charge for example.

name

string

The article name.

price

bigint

The gross unit price in the minor currency unit.

If you pass a value of 1595 for a order in Euros, this means 1,595 Euro Cents, or €15.95.

tax

bigint

The value-added tax (VAT) rate in percent.

If you pass a value of 19, this means a VAT rate of 19%.

Stakeholder Shares

Passing a stakeholder payment works very similar to passing an article. The stakeholder payment is passed as a special basket item.

Each stakeholder is a JavaScript object in the basket, having these properties:

  • item type for stakheolder payment;

  • contract ID of the payee;

  • the amount of this share.

secupayCheckout.setBasket([
// some articles first, then our stakeholder share ...
{
id: 1000,
itemType: "stakeholder_payment",
contractId: "GCR_yyy",
price: 73
}
]}

There can also be more than one share.

Detailed description of the objects for the basket items:

Attribute

Type

Description

id

bigint

Optional. Item ID to manage the item later.

itemType

string

Always "stakeholder_payment".

contractId

string

The contract ID of the payee. The share will be paid out to this contract.

price

bigint

The amount of the share in the minor currency unit.

If you pass a value of 73 for a order in Euros, this means 73 Euro Cents, or €0.73.

Start the Smart Checkout

Given the needed options are set, and there is something in the basket, you can start the checkout process.

You can either start:

  • the longer order flow;

  • the short payment flow.

In the order flow the Smart Checkout can also deal with the delivery details, and offers you Click & Collect if in the contract. There are some e-mails sent, specific for orders. And you find the order with all details in the Completed Orders view of SecuOffice.

The payment flow can be only one page to authenticate or start the payment.

Start the Smart Checkout for Order

To start the Smart Checkout with the full order process, you simply call secupayCheckout.enterCheckout(), as shown in the Getting Started section.

Start the Smart Checkout for Payment

To start the Smart Checkout with the full order process, you simply call secupayCheckout.enterPayment(). It will start with a payment method selection, except there is only one method.

Troubleshooting

Situation

What to do?

The Checkout Wizard does not start at all.

There are two main reasons:

(1) The JavaScript is not included properly. Please check whether the <script> tag is there, and the browser can load the JavaScript from https://checkout.secupay.com/assets/js/secupay-checkout.js. Usually you can see this in the network pane of the developer tools of your browser. In Chrome or Firefox you can open and close the developer tools by pressing F12. If it fails to load, check the <script> tag for typos. If not loaded properly, you should also see an error message like "ReferenceError: secupayCheckout is not defined" in the JavaScript console of the developer tools.

(2) The method secupayCheckout.enterCheckout() is not called for some reason. You can check this in the debugger view of the developer tools. It is likely you call the method in a event handler for either the click event, or the submit event of a form. Then you would register a breakpoint for these event, operate your controls, and step into the event handler.

The Checkout Wizard immediately shows an error page, or the preloader does not stop to cycle.

The parameters are misconfigured or the basket is empty.

First, check whether you find something helpful in the JavaScript console of the developer tools of your browser. In Chrome or Firefox you can open and close the developer tools by pressing F12. After opening the log console repeat your actions.

If you could not find something helpful in the JavaScript console, please get in touch with our help desk. Describe the situation, tell your contract ID and the exact time, and ask to check the error logs for the exact reason.

The Checkout Wizard starts in a small window inside the page:

images/plugins/servlet/confluence/placeholder/unknown-attachment.png

The CSS is not included properly. Please check whether the <link rel="stylesheet"> tag is there, and the browser can load the CSS file from https://checkout.secupay.com/assets/css/secupay-checkout.css. Usually you can see this in the network pane of the developer tools of your browser. In Chrome or Firefox you can open and close the developer tools by pressing F12. If it fails to load, check the <link> tag for typos.

I don't see the completed order in SecuOffice.

Did you replace the contract ID in our examples with your individual one? See above, Globale Options, attribute contractId.

I don't receive a payment.

Did you switch from demo to production? See above, Globale Options, attribute isDemo.

After fixing this: For technical reasons it is not possible to change a demo transaction in a productive one. The buyer needs to repeat the checkout.

In SecuOffice you can see for every order whether it was placed in demo mode. So usually you would see it before you process the order.

I received a payment in my tests.

Did you set isDemo: true? See above, Globale Options, attribute isDemo.

After fixing this: Please cancel the transaction fully.

After switching from demo into production, the Checkout Wizard starts with an error page. Or there are fewer payment options than before.

The onboarding process has not been completed and productive settings are not yet available. Your contract might be configured for demo transactions only. Perhaps the the beneficial owners are not identified fully.

If the reason is not known to you, please get in touch with our help desk or our customer service.