Integration Guide for Orders (Smart Checkout / secuconnect API)

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.

The API integration can be used with or without a storefront application. You can prepare an order, and make the checkout start in two different ways. There is a URL that can be used in your online shop. But you can also print it in a QR code, sent it via chat, mail, etc., etc. Further you use a generated ID, and make some small parts of frontend code by secupay start the Checkout Wizard in a model layer above your shop page.

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 prepare your order using the secuconnect API by secupay. Then we start the Checkout Wizard full screen. You should have basic knowledge of web development and API programming. Our secuconnect API implements REST, and uses JSON for the payload.

First you will learn a few basic key terms. Then we demonstrate the integration step by step with a working example that can be integrated into 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 API integration, this is the standard checkout flow:

  1. The customer decides for some goods in the merchant's shop, and finally asks for checkout.

  2. The merchant's shop prepares a Smart Transaction using the secuconnect API.

  3. The merchant's shop starts the Checkout Wizard by secupay, either using the provided URL or using the HTML or 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

In our example we will do the mininum. We will authenticate against the secuconnect API, create a Smart Transaction, and open the Checkout Wizard.

Step 1: Authenticate Against secuconnect API

Most API calls require authentication. The secuconnect API uses the OAuth 2.0 protocol for authentication. The OAuth service checks your credentials, and hands an access token over to you. It grants you access to the API for a limited period of time. The client must pass this token with all subsequent API calls.

The endpoint for OAuth authorization is POST https://connect.secucard.com/ oauth/token.

Example request:

POST /oauth/token HTTP/1.1
Host: connect.secucard.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 151
 
grand_type=client_credentials&client_id=129b362607f87990bdf5589a0be3a04d&client_secret=31e991b25b7896a3fad567507f7eb38feaef9329657a4a8cd30fbe6eecf5f50b

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
...
 
{
"access_token": "qb56tjj1bcvo9n2nj4u38k84lo",
"expires_in": 1200,
"token_type": "bearer",
"scope": "https://scope.secucard.com/e/api"
}

The returned access token is valid for as many seconds as signalised in the expires_in field (line 8). You need to pass the received token (line 7) in an HTTP request header Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo of the subsequent calls.

Usually, direct usage of HTTPS is not necessary, but for can be useful for debugging and to understand the SDK.

The corresponding example using the secuconnect PHP SDK:

use \Secuconnect\Client\Configuration;
use \Secuconnect\Client\Authenticator;
use \Secuconnect\Client\OauthCredentials;
 
// Optionally you can configure a PSR-6 compliant cache
Configuration::getDefaultConfiguration()->setCache($cache);
 
// Create an authenticator object with OAuth authentication and obtains token
$auth = new Authenticator(OauthClientCredentials::from($clientId, $clientSecret));
$accessToken = $auth->getToken();
 
// Saves the token to the default client configuration
Configuration::getDefaultConfiguration()->setAccessToken($accessToken);

We provide SDKs for PHP, Java, NodeJS, and .NET free of charge.

Step 2: Create A Smart Transaction

The API endpoint to create a Smart Transaction is POST https://connect.secucard.com/api/v2/Smart/Transactions.

Example request:

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
...
 
{
"is_demo": true,
"intent": "order",
"contract": {
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
"basket": {
"products": [
{
"id": 0,
"desc": "ACME ball pen Modern Line 8050",
"priceOne": 1595,
"tax": 19,
"quantity": 2
},
{
"id": 1,
"desc": "ACME pen case Modern Line",
"priceOne": 1795,
"tax": 19,
"quantity": 1
}
]
},
"basket_info": {
"sum": 4985
},
"order_option": "shipping"
}

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
...
{
"object": "smart.transactions",
"id": "STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ",
"merchant": {
"object": "general.merchants",
"id": "MRC_AZS7P6FTNTC6NK0QWFDBREW94ZY2O7",
"companyname": "Smart Checkout Testmerchant 8"
},
...
"contract": {
"object": "general.contracts",
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
...
"created": "2020-02-04T15:34:00+01:00",
"status": "created",
...
"basket": {
"products": [
{
"id": 0,
"parent": null,
"articleNumber": null,
"ean": null,
"desc": "ACME ball pen Modern Line 8050",
"quantity": 2,
"priceOne": 1595,
"tax": 19,
"group": null,
"serialNumber": null,
"item_type": "article",
"reference_id": null
},
{
"id": 1,
"parent": null,
"articleNumber": null,
"ean": null,
"desc": "ACME pen case Modern Line",
"quantity": 1,
"priceOne": 1795,
"tax": 19,
"group": null,
"serialNumber": null,
"item_type": "article",
"reference_id": null
}
],
...
},
"basket_info": {
"sum": 4985,
"currency": "EUR",
...
},
"order_option": "shipping",
"is_demo": true,
...
"checkout_links": {
"url_checkout": "https://checkout.secupay.com?wizardFlow=checkout&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&viewMode=fullscreen"
},
...
}

As you see, the secuconnect implementation added a lot of things. Most interesting for you are the ID of the Smart Transaction (line 8), and the checkout URL (line 65).

Step 3: Open The Checkout Wizard

In general there are two ways to start the Checkout Wizard. You can make the customer open the checkout URL directly. You can offer the URL in your web application, send it by mail, etc., etc. On the other hand you can embed some frontend code provided by secupay, and pass the Smart Transaction ID to it. It can open the wizard in a nice layer above your page.

We simply put the URL from checkout_links/url_checkout into our browser's address bar. This opens the Checkout Wizard full screen:

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

As you see, it is very simple.

Summary

You have seen how to integrate our Checkout Wizard with your website using our secuconnect API. We prepared a Smart Transaction for the order, and started the Checkout Wizard in a browser.

Furthermore you can:

  • Let our secuconnect SDKs make the work of assembling the requests, and parsing the response

  • 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

  • Let integration code provided by secupay start the Checkout Wizard in a layer

  • 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

  • Preset the Smart Transaction with known customer data

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

There is also separate guide for marketplaces, which need to pass a mixed basket for multiple merchants.

Reference

Demo or Production

You can create your particular Smart Transaction in demo mode. This is useful for testing, especially during integration.

{
"is_demo": true,
...
}

For demo transactions, no payment is being processed. Demo transactions can be filtered and excluded in SecuOffice.

The demo mode is a boolean value:

  • true: The Smart Transaction is marked as demo transaction. The payment is not processed.

  • false: The Smart Transaction is handled as a productive one. The payment will be processed.

The default value is false, a productive transaction.

There can be different payment methods configured for demo and production. If a particular payment method is available in production mode, it must not necessarily be in demo mode, and vice versa.

Do not forget to change the parameter when you make tests including our live system. Also do not forget to switch to prduction, when you go live. The resulting transaction cannot be changed anymore, but only be cancelled.

Pure Checkout or Order Processing

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.

You can pass the intent as attribute of the STX:

{
"intent": "checkout",
...
}

Start Checkout By URL

If the Smart Transaction is prepared for checkout, you can access the checkout URL in the field checkout_links/url_checkout:

{
"object": "smart.transactions",
"id": "STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ",
...
"checkout_links": {
"url_checkout": "https://checkout.secupay.com?wizardFlow=checkout&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&viewMode=fullscreen
},
...
}

It is up to the merchant to offer this URL to the prospective customer.

A few suggestions:

  • It can be opened full screen in a browser using an <a> tag.

  • It can be opened in a modal layer that is able to show an arbitrary HTTP source.

  • It can be sent via e-mail or in a chat window to a known customer.

When you integrate it into a web application you should define return URLs. There is a section below, that describes how to define them. But as you see it is not bound to a website or web application.

When you open the Checkout Wizard in a layer, you need to consider that it might switch to full screen mode. This is needed for instance for the 3-D Secure checks.

The return URLs will always open in full screen and replace the former window.

Start Checkout In Layer

If the Smart Transaction is prepared for checkout, you can also open it in a layer using the frontend integration code provided by secupay. In order to achive this, you need to integrate a CSS and a JavaScript file. Then you pass the ID to it.

Include Needed JavaScript and CSS

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.

Now you can start the checkout either using the means of HTML or JavaScript.

Start Checkout Wizard Using HTML

You can start the checkout with an HTML form. The form needs the class sc-autobasket-form and an attribute data-sc-stx with your particular STX ID.

<form data-sc-stx="STX_3P69AAKAN2N9QYRRD3H58FNFY7B6A2" class="sc-autobasket-form">
<button class="sc-autobasket-enter-button">Check out now</button>
</form>

Include this code within the <body> of your page. When you click the button, the Checkout Wizard appears as either a layer over your page or in full screen, depending on your browser.

Start Checkout Wizard Using JavaScript

In order to start the checkout you need to run the function enterCheckout():

function checkoutHandler() {
secupayCheckout.setOptions({
urlParams: { stx: "STX_3P69AAKAN2N9QYRRD3H58FNFY7B6A2" }
});
secupayCheckout.enterCheckout();
}

You can call this JavaScript function from an HTML button, for example. The Checkout Wizard appears either as a layer over your page or in full screen, depending on your browser.

Basket Details

The basket items are passed in the object node basket/products. They need to have these mandatory details:

  • item ID;

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

{
...
"basket": {
"products": [
{
"id": 0,
"articleNumber": "ACM/BPMOD-8050",
"ean": "4123456789012",
"desc": "ACME ball pen Modern Line 8050",
"quantity": 2,
"priceOne": 1595,
"tax": 19
},
{
"id": 1,
"articleNumber": "ACM/CASMOD",
"ean": "4123500055537",
"desc": "ACME pen case Modern Line",
"quantity": 1,
"priceOne": 1795,
"tax": 19
}
],
...
},
"basket_info": {
"sum": 4985,
"currency": "EUR",
...
},
...
}

Detailed description of the objects for the basket items:

Attribute

Type

Description

id

number

The item ID as integer. It is necessary as handle for further changes.

quantity

number

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

number

The gross unit price in the minor currency unit.

If you pass a value of 1595 for a order in Euros, this means 1595 Euro Cents, or €15,95.

tax

number

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

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

Individual Return URLs

The Checkout Wizard can return the user to your website, if you have defined the needed URLs. The URLs cover two cases, successful or failed checkout. For instance if the user aborts the checkout procedure, or there is a technical reason.

You can define the return URLs statically in SecuOffice, or you can pass individual URLs for every particular Smart Transaction. These individual URLs for the Smart Transaction override the static ones from SecuOffice.

Here an example how to pass both individual return URLs:

{
...
"basket": {
...
},
"application_context": {
"return_urls": {
"url_success": "https://www.example.com/survey?sessid=1X23Y4Z5",
"url_failure": "https://www.example.com/basket?sessid=1X23Y4Z5&reason=CHOUTFAIL"
}
},
...
}

If there is a success URL, whether static or individual, the user is offered a back-to-shop-link:

images/download/attachments/87393716/image2020-1-23_13-26-48.png

The failure URL for instance is used when the user stops the checkout prematurely, using the X button in the top-right corner:

images/download/attachments/87393716/image2020-1-23_13-34-54.png

This is only possible, if a failure URL is present. The user is prompted to confirm the operation. A second confirmation is required to abort and initiate a redirect to the provided URL.

Not all scenarios can be covered by these URLs. For example, if there is a browser session timeout, the URLs cannot be resolved.

Default Language

You can pass a default language for the Checkout Wizard.

Currently, these languages are supported:

  • de_DE (German)

  • en_GB (English)

If you omit a default language, the Checkout Wizard starts in German.

Use secuconnect SDKs

We offer several SDKs to assist you in the integration of our secuconnect API. Currently, PHP, Java and Node JS are available.

The documentation and examples can be found at https://developer.secuconnect.com/.

Further examples and the sources are available at https://github.com/secuconnect.

There packages can also be included using Composer and the Packagist repository (PHP), Gradle (Java), or NPM with or without Browserify (server-side or browser-side JavaScript).

Troubleshooting

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.


Left over so far:

To complete this integration, you should have an understanding how REST API works.

Fehler beim Ausführen des Makros 'include'

com.atlassian.renderer.v2.macro.MacroException: Es wurde kein Seitenname zur Verfügung gestellt.

Fehler beim Ausführen des Makros 'include'

com.atlassian.renderer.v2.macro.MacroException: Es wurde kein Seitenname zur Verfügung gestellt.

(...)