Introduction

This integration guide explains how to implement the product Smart Checkout into a web application. The HTML variant described here is the simplest and fastest solution to integrate the Smart Checkout.

Described Product

Smart Checkout

The Smart Checkout is an easy and convenient way to pay. If user and the device are known, the payment process can be completed in one click (Feature still in development).

The secupay Smart Checkout combines eCommerce and mobile commerce with POS terminals and cash registers. This results in cross-channel solutions for retailers and service providers who offer their goods and services both on the Internet and locally, and want to connect the two channels with each other. Ideally, the customer can place an order and and pay for it at each point of contact, or cancel it if they wish. Contact points can be mobile devices such as smartphones, or located at billboards, on a PC or in a shop.

Checkout Wizard

The Checkout Wizard is part of the Smart Checkout. Using the Wizard, customers can enter their data to complete an order.

Who should use this Guide?

This tutorial is intended for users with basic knowledge of HTML who want to integrate the Smart Checkout into their (shop) system. It is mainly intended for simple systems. For more complex applications, we recommend the integration via JavaScript. With this basic version of the secupay Smart Checkout you will receive a payment solution with an integrated order process. The orders received can be viewed and processed in our backoffice application, SecuOffice.

Structure

The first part of the guide describes the basic steps required to get a functional Smart Checkout for productive operation.

The main goal of this guide is the simple integration of the Checkout Wizard. Further adjustments to the layout can be made if necessary. Extended use cases are described after basic integration.

Getting Started

At the end of this section, your website or shop will have a simple, functional Checkout Wizard like the one displayed below.

 

Tools Needed

No special software is necessary for the integration of the wizard. You create or edit HTML files with any conventional text editor. We recommend the use of Notepad++. The free software can be downloaded here: https://notepad-plus-plus.org/download

Scripting

The following example script shows how to integrate two products with different criteria. A step-by step guide explains how to implement this into your website.

Adjust the layout, elements' size and other options depending on your needs and your existing website. Instructions on how to do so can be found later in this guide and the external sources.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <link rel="stylesheet" href="https://checkout.secupay.com/assets/css/secupay-checkout.css"/>
    <script src="https://checkout.secupay.com/assets/js/secupay-checkout.js"></script>
</head>
<body>
<form class="sc-autobasket-form"
      data-sc-contract-id="GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
      data-sc-is-demo="true"
      data-sc-url-success=""
      data-sc-url-failure=""
      data-sc-url-abort=""
      data-sc-url-error=""
      data-sc-lang="" 
      data-sc-shop-url="" 
      data-sc-view-mode="" 
      >
 
   <div class="sc-autobasket-item">
    <input type="number"
           data-sc-item-name="Test Item 1"
           data-sc-item-ean="123456" 
           data-sc-item-price="1500"
           data-sc-item-tax="19" 
           data-sc-item-id="555" 
           data-sc-item-article-number="666" 
           min="1" 
           max="99"
           step="1" 
           value="0"/> 
          Test Item 1 
     
        </div>
        <div class="sc-autobasket-item">
        <input type="checkbox"
               data-sc-item-name="Test Item 2"
               data-sc-item-ean="11112"
               data-sc-item-price="6000" 
               data-sc-item-tax="7"
               data-sc-item-id="888"
               data-sc-item-article-number="213"
                data-sc-item-quantity="5" 
                />
        Test Item 2
</div>
        
        <div class="sc-autobasket-enter-button">Buy Now</div>
      
  
</form>

</body>
</html>

Integration Checkout Wizard

Three steps are required to integrate the Checkout Wizard into your website:

  1. Include the Wizard's CSS and JavaScript.
  2. Add the shop description and items.
  3. Link Webpage and Smart Checkout.

Step 1: Include the Wizard's CSS and JavaScript 

Include File secupay-checkout.css

Insert this file in the <head> section of your page.

The file determines the appearance and layout of the Checkout Wizard.

<link rel="stylesheet" href="https://checkout.secupay.com/assets/css/secupay-checkout.css"/>

Include File secupay-checkout.js

Insert this file in the <head> section of your page.

The file includes JavaScript, required to call the Checkout Wizard.

<script src="https://checkout.secupay.com/assets/js/secupay-checkout.js"></script>

Step 2: Add the Shop Description and Items

Setting Contract Values

Insert this script in the <body> section of your page.

This data applies to all elements within the <form> tag. On one page, several checkouts are possible; each checkout is one <form> and each <form> element (e.g. input) defines the basket items.

<form class="sc-autobasket-form"
      data-sc-contract-id=""
      data-sc-is-demo="true"
	>
</form>

Enter your personal contract number under contractId:. It always starts with the prefix "GCR_"

Configuring Basket

Add each item according to the following pattern (applies to article only):

 <div class="sc-autobasket-item">
    <input type="number"
           data-sc-item-name="Testartikel 1"
           data-sc-item-ean="123456" 
           data-sc-item-price="1500"
           data-sc-item-tax="19" 
           data-sc-item-id="555" 
           data-sc-item-article-number="666" 
           min="1" 
           max="99"
           step="1" 
           value="0"/> 

What these values mean

ValueDescriptionNotes

<div class="sc-autobasket-item">

Itemclass

Each item must be defined in this class

<input type="number"

Defines the type of selection

Other options: Checkbox, Radio button, Dropdown

data-sc-item-name="Test Item 1"

Product name within the shopping cart


data-sc-item-ean="123456"

EAN of the article


data-sc-item-id="555"

Unique ID of the article


data-sc-item-article-number="666"

Item number (unique)


in="0

minimum amount

optional

max="99"

maximum amount

optional, cannot be zero

step="1"

incrementation

value="0"

preset value


Step 3: Link Webpage and Smart Checkout 

<body>
  <!-- ... your page content here ... -->
 
  <script type="application/javascript">
    secupayCheckout.registerFormById("sales-form");
  </script>
</body>

This concludes the basic integration of the Checkout Wizard. The next section will show you how to add more parameters and customise the layout.

Integration with creating the Smart Transaction via API

Creating the smart Transaction via API is a more secure way to transmit the basket, because data that cannot be modified. With the API integration the basket can be validated as well.

  1. Send request to API after basket is filled
  2. API will create STX
  3. API returns STX to the webshop
  4. URL is generated that initiates the Checkout
  5. Checkout Wizard takes over
{
  "is_demo": true,
  "basket": {
    "products": [
      {
        "id": 0,
        "articleNumber": "10002",
        "ean": "2134659754",
        "desc": "Something",
        "quantity": 1,
        "priceOne": 1,
        "tax": 7
      }
    ]
  },
  "basket_info": {
    "sum": 1
  },
  "contract": {
    "id": "GCR_ND7CT5PFTPBDMD935R50YARMKZK0PG"
  },
    "order_option": "shipping",
}
{
    "object": "smart.transactions",
    "id": "STX_WCSY3J8JM2N8A4B3DPDC840FM57NAH",
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_AZS7P6FTNTC6NK0QWFDBREW94ZY2O7",
        "companyname": "Smart Checkout Testmerchant 8"
    },
    "provider_contract": {
        "object": "general.contracts",
        "id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8"
    },
    "contract": {
        "object": "general.contracts",
        "id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
    },
    "transactions": [],
    "created": "2019-06-19T13:55:50+02:00",
    "updated": "2019-06-19T13:55:50+02:00",
    "status": "created",
    "transactionRef": null,
    "merchantRef": null,
    "basket": {
        "products": [
            {
                "id": 0,
                "parent": null,
                "articleNumber": "10002",
                "ean": "2134659754",
                "desc": "Something",
                "quantity": 1,
                "priceOne": 1,
                "tax": 7,
                "group": null,
                "serialNumber": null,
                "item_type": "article",
                "reference_id": null
            }
        ],
        "texts": [],
        "type": "default"
    },
    "basket_info": {
        "sum": 1,
        "gratuity": null,
        "currency": "EUR"
    },
    "order_option": "shipping",
    "is_demo": true,
    "checkout_links": {
        "url_checkout": "https://iframe-dev.secupay-ag.de?stx=STX_WCSY3J8JM2N8A4B3DPDC840FM57NAH&server=showcase"
    },
    "idents": null
}

Additional Parameters and Layout

This section deals with more specific use cases that provide additional configuration options for advanced users. Using the advanced methods, the Checkout Wizard can be adjusted to your needs.

Advanced Example: Autobasket with Bootstrap

Bootstrap is a type of CSS Framework. Frameworks are predefined scripts that add complete components such as menus, sliders or tabs to your website.

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <meta name="description" content="">
    <meta name="author" content="">

    <title>Example of Smart Checkout with Autobasket</title>

    <!-- Bootstrap core CSS -->
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css"
          integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
    <link rel="stylesheet" href="https://checkout.secupay.com/assets/css/secupay-checkout.css">

    <script src="https://checkout.secupay.com/assets/js/secupay-checkout.js"></script>

</head>

<body>

<div class="d-flex flex-column flex-md-row align-items-center p-3 px-md-4 mb-3 bg-white border-bottom shadow-sm">
    <h5 class="my-0 mr-md-auto font-weight-normal">Example of Smart Checkout with Autobasket</h5>
    <nav class="my-2 my-md-0 mr-md-3">
        <a class="p-2 text-dark" href="#">Top link 1</a>
        <a class="p-2 text-dark" href="#">Top link 2</a>
        <a class="p-2 text-dark" href="#">Top link 3</a>
        <a class="p-2 text-dark" href="#">Top link 4</a>
    </nav>
</div>

<div class="pricing-header px-3 py-3 pt-md-5 pb-md-4 mx-auto text-center">
    <h1 class="display-4">Buy with Smart Checkout</h1>
    <p class="lead">This example is base on Boostrap library with integrated Smart Checkout</p>
    <p class="lead">Set product quantity, add to basket and pay </p>
</div>


<div class="container">
    <form class="sc-autobasket-form"
          data-sc-contract-id="GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
          data-sc-is-demo="true"
          data-sc-url-success=""
          data-sc-url-failure=""
          data-sc-url-abort=""
          data-sc-url-error=""
          data-sc-lang=""
          data-sc-shop-url=""
          data-sc-view-mode="">
        <div class="card-deck mb-3 text-center">
            <div class="card mb-4 shadow-sm">
                <div class="card-header">
                    <h4 class="my-0 font-weight-normal">Bronze</h4>
                </div>
                <div class="card-body sc-autobasket-item">
                    <h1 class="card-title pricing-card-title">50 €</h1>
                    <ul class="list-unstyled mt-3 mb-4">
                        <li>10 users included</li>
                        <li>2 GB of storage</li>
                        <li>Email support</li>
                        <li>Help center access</li>
                    </ul>
                    <input type="number"
                           data-sc-item-name="Bronze"
                           data-sc-item-ean="111222333"
                           data-sc-item-price="5000"
                           data-sc-item-tax="7"
                           data-sc-item-id="1212"
                           data-sc-item-article-number="999"
                           min="0"
                           step="1"
                           value="0"
                           class="form-control text-right"/>
                </div>
            </div>
            <div class="card mb-4 shadow-sm">
                <div class="card-header">
                    <h4 class="my-0 font-weight-normal">Gold</h4>
                </div>
                <div class="card-body sc-autobasket-item">
                    <h1 class="card-title pricing-card-title">100 €</h1>
                    <ul class="list-unstyled mt-3 mb-4">
                        <li>20 users included</li>
                        <li>10 GB of storage</li>
                        <li>Priority email support</li>
                        <li>Help center access</li>
                    </ul>
                    <select
                            data-sc-item-name="Gold"
                            data-sc-item-ean="554"
                            data-sc-item-price="10000"
                            data-sc-item-tax="15"
                            data-sc-item-id="7558"
                            data-sc-item-article-number="80"
                            class="form-control">
                        <option value="0">0</option>
                        <option value="1">1</option>
                        <option value="2">2</option>
                        <option value="3">3</option>
                        <option value="4">4</option>
                        <option value="5">5</option>
                        <option value="6">6</option>
                    </select>
                </div>
            </div>
            <div class="card mb-4 shadow-sm">
                <div class="card-header">
                    <h4 class="my-0 font-weight-normal">Platinium</h4>
                </div>
                <div class="card-body sc-autobasket-item">
                    <h1 class="card-title pricing-card-title">200 €</h1>
                    <ul class="list-unstyled mt-3 mb-4">
                        <li>30 users included</li>
                        <li>15 GB of storage</li>
                        <li>Phone and email support</li>
                        <li>Help center access</li>
                    </ul>
                    <input type="checkbox"
                           data-sc-item-name="Platinium"
                           data-sc-item-ean="111222333"
                           data-sc-item-price="20000"
                           data-sc-item-tax="7"
                           data-sc-item-id="12132"
                           data-sc-item-article-number="999"
                           data-sc-item-quantity="1"
                           class="from-control"
                    />
                </div>
            </div>
        </div>
        <div class="sc-autobasket-total-sum text-center p-3">
            Total sum: <span></span>
        </div>
        <div class="sc-autobasket-enter-button button button-primary">
            Pay with Smart Checkout
        </div>
        <div class="bg-light p-3 m-3">
            HINT: In DevTools' console you can see all basket details
        </div>
    </form>

    <footer class="pt-4 my-md-5 pt-md-5 border-top">
        <div class="row">
            <div class="col-12 col-md">
                <img class="mb-2" src="../../assets/brand/bootstrap-solid.svg" alt="" width="24" height="24">
                <small class="d-block mb-3 text-muted">&copy; 2017-2018</small>
            </div>
            <div class="col-6 col-md">
                <h5>Features</h5>
                <ul class="list-unstyled text-small">
                    <li><a class="text-muted" href="#">Link 1</a></li>
                    <li><a class="text-muted" href="#">Link 2</a></li>
                    <li><a class="text-muted" href="#">Link 3</a></li>
                    <li><a class="text-muted" href="#">Link 4</a></li>
                    <li><a class="text-muted" href="#">Link 5</a></li>
                    <li><a class="text-muted" href="#">Link 6</a></li>
                </ul>
            </div>
            <div class="col-6 col-md">
                <h5>Resources</h5>
                <ul class="list-unstyled text-small">
                    <li><a class="text-muted" href="#">Link A</a></li>
                    <li><a class="text-muted" href="#">Link B</a></li>
                    <li><a class="text-muted" href="#">Link C</a></li>
                    <li><a class="text-muted" href="#">Link D</a></li>
                </ul>
            </div>
            <div class="col-6 col-md">
                <h5>About</h5>
                <ul class="list-unstyled text-small">
                    <li><a class="text-muted" href="#">Link W</a></li>
                    <li><a class="text-muted" href="#">Link X</a></li>
                    <li><a class="text-muted" href="#">Link Y</a></li>
                    <li><a class="text-muted" href="#">Link Z</a></li>
                </ul>
            </div>
        </div>
    </footer>
</div>

<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js"
        integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo"
        crossorigin="anonymous"></script>
</body>
</html>

Advanced page settings: Remote URLs and Language

<form class="sc-autobasket-form"
      data-sc-contract-id=""
      data-sc-is-demo="true"
      data-sc-url-success="" 
      data-sc-url-failure=""
      data-sc-url-abort=""
      data-sc-url-error=""
      data-sc-lang="" 
      data-sc-shop-url="" 
      data-sc-view-mode="" 
      >

</form>

What these values mean

ValueDescriptionNotes

data-sc-contract-id

Defines the contract IDmandatory

data-sc-is-demo

Determines whether transactions will be done on demo or live mode. For testing, set demo to true.If the demo option is omitted, this has the same effect like isDemo: false

data-sc-url-success

Dynamic URL to return to the shop after successful order. It overrides the static success return URL of your contract settings.

optional

data-sc-url-failure

Dynamic URL to return after user abort or after an unrecoverable erroroptional

data-sc-url-abort

Dynamic URL to return after user abort.optional

data-sc-url-error

Dynamic URL to return after an unrecoverable error.optional

data-sc-lang

Initial language for the Smart Checkout. Has two options: DE_DE or EN_GBoptional

data-sc-shop-url

URL to merchant's shopoptional

data-sc-view-mode

For fullscreen view mode we can pass additional parameters to activate the Checkout iFrame:

  • viewMode (layer, fullscreen)
  • shopUrl (URL to merchant's shop)
optional

Add Interactive Basket Summary

You can display a summary of all items currently inside the basket. This will show the quantity, productname, item price with and without VAT, VAT in % (Ust.) and the full price. The title can be adjusted by setting data-sc-title="My basket".

 <div class="sc-autobasket-basket-summary"
         data-sc-title="My basket"
 ></div>

Show Total Sum

In order to show the total sum as items are being selected, add this code after all of your baskets.

<div class="sc-autobasket-total-sum">
    Total sum: <span></span>
</div>

The description Total sum can be changed. Please note that <span></span> is a required element.

Additional Basket Types

Basket with Radio Buttons

Radio buttons can be used as a group for the user to make a selection. Only one button can be active. Please note these buttons cannot be unchecked.

<div class="sc-autobasket-item">
    <input type="radio"
           data-sc-item-name=""
           data-sc-item-ean=""
           data-sc-item-price=""
           data-sc-item-tax=""
           data-sc-item-id=""
           data-sc-item-article-number=""
           data-sc-item-quantity=""
           name="NAME_MUST_BE_THE_SAME_FOR_ALL_ELEMENTS_IN_GROUP"
    />
    <input type="radio"
           data-sc-item-name=""
           data-sc-item-ean=""
           data-sc-item-price=""
           data-sc-item-tax=""
           data-sc-item-id=""
           data-sc-item-article-number=""
           data-sc-item-quantity=""
           name="NAME_MUST_BE_THE_SAME_FOR_ALL_ELEMENTS_IN_GROUP"
           checked="checked"
    />
</div>

Basket with Input Options

Additional options allow you to add extras or discounts to an item. Price modifiers can be set as number values or percent, with positive or negative values (+/-).

<div class="sc-autobasket-item">
  <input ... />
  <input type="checkbox" data-sc-item-price="20%" />
  <input type="checkbox" data-sc-item-price="-150" />
</div>

Basket with multiple Checkboxes per Item

Using this code, you can add more than one checkbox per item. But only one checkbox can be active. 

 <div class="sc-autobasket-item">
        <label>My first checkbox</label>
        <input type="checkbox"
               data-sc-item-name="Checkbox only"
               data-sc-item-ean="111222333"
               data-sc-item-price="1000"
               data-sc-item-tax="7"
               data-sc-item-id="12132"
               data-sc-item-article-number="999"
               data-sc-item-quantity="1"
        />
        <br />

        <label>My second checkbox</label>
        <input type="checkbox"
               data-sc-item-name="Checkbox only"
               data-sc-item-ean="111222333"
               data-sc-item-price="5040"
               data-sc-item-tax="7"
               data-sc-item-id="1214321"
               data-sc-item-article-number="999"
               data-sc-item-quantity="2"
        />
        <br />

        <label>My third checkbox</label>
        <input type="checkbox"
               data-sc-item-name="Checkbox only"
               data-sc-item-ean="111222333"
               data-sc-item-price="51000"
               data-sc-item-tax="7"
               data-sc-item-id="1213221"
               data-sc-item-article-number="999"
               data-sc-item-quantity="2"
        />
    </div>

It is also possible to add the checkbox first and label (text) afterwards. To use checkboxes separately, put each in a <div class="sc-autobasket-item"></div> wrapper.

Basket with Dropdown Selector

Basket items can be selected via a dropdown using the following code. You can set individual prices for items using data-sc-item-price="1000":

<div class="sc-autobasket-item">
 <select data-sc-item-name="Product"
 data-sc-item-ean="00000010"
 data-sc-item-price="1500"
 data-sc-item-tax="19"
 data-sc-item-id="0010"
 data-sc-item-article-number="0010" >
 <option value="0" selected>0</option> 
 <option value="1">1</option>
 <option value="2">2</option>
 <option value="3" data-sc-item-price="1000">3</option>
 <option value="4">4</option></select>
</div>

Testing the Smart Checkout

After you have configured your Checkout Wizard, you should complete a demo transaction.

  1. Make sure the demo parameter is set: data-sc-is-demo="true"
  2. Fill your Basket.
  3. Click the Buy Now Button.
  4. Enter your Email and, optional: date of birth.
  5. Enter your address details.
  6. Choose one of your activated payment methods.
  7. Confirm your Purchase.

If everything worked fine you will see a success page. Login to your secuOffice account and check if the transaction has been created correctly.

Going Live

  1. Make sure you have completed a demo transaction and
  2. check all values in secuOffice.
  3. Find the parameter data-sc-is-demo="true" (default) and
  4. change the parameter to data-sc-is-demo="false".

Troubleshooting

Typical Errors

After basic integration, the Checkout Wizard shows an error page

Possible reasons:

  1. The Basket format is incorrect. Please check the data you sent.
  2. The Contract ID is invalid. Check if it is correct.
  3. Your contract has no payment conditions, or it has expired. Make sure you have an active contract.

Further Reading

HTML Basics

https://www.w3schools.com/html/default.asp - Developer site with definitions, tutorials and examples on how to build a website.