Integration Guide for Mixed Baskets (Smart Checkout / secuconnect API)

Introduction

Fehler beim Ausführen des Makros 'include'

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

This guide will show you how to integrate the Checkout Wizard with your marketplace solution by using two calls to our secucuonnect API and providing a checkout URL to the buyer. This guide also introduces mixed baskets, needed to place orders from multiple merchants and stakeholder payments that handle payout of marketplace fees.

Fehler beim Ausführen des Makros 'include'

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

Business Model, Roles and Objects

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.

Getting Started

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

Depending on your contract settings, these values may differ or you may have additional settings enabled. Please refer to your key account manager for assistance.

  1. Smart Checkout needs to be enabled in contract settings.

  2. You need to have your credentials consisting of client_id and client_secret at hand. You will receive these credentials from the secupay support.

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.

Fehler beim Ausführen des Makros 'include'

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

Create a Smart Transaction

To create a smart transaction (STX) send a post request to POST request to https://connect.secucard.com/api/v2/Smart/Transactions.

Example Request Body
{
"is_demo": true,
"contract": {
"id": "<marketplace contract_id>"
},
"provider_contract": {
"id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8" // Smart Checkout provider contract id
},
"basket": {
"products": [
{
"item_type": "sub_transaction",
"desc": "Position 2 Order something",
"sum": 999,
"reference_id": "1002",
"contract_id": "<seller_contract_id>",
"sub_basket": [
{
"id": 1,
"parent": null,
"articleNumber": null,
"ean": null,
"desc": "cola 0.33 ltrs.",
"quantity": 1,
"priceOne": 500,
"tax": 19,
"group": null,
"serialNumber": null,
"item_type": "article",
"reference_id": "1002/item1"
},
{
"id": 2,
"parent": null,
"articleNumber": null,
"ean": null,
"desc": "cheese burger",
"quantity": 1,
"priceOne": 499,
"tax": 19,
"group": null,
"serialNumber": null,
"item_type": "article",
"reference_id": "1002/item2"
},
{
"item_type": "stakeholder_payment",
"desc": "stakeholder_1",
"sum": 5,
"reference_id": "1002/share2",
"contract_id": "<stakeholder_gcr_id>"
}
]
}
],
"texts": [],
"type": "mixed"
},
"basket_info": {
"sum": 999
},
"order_option": "shipping"
}

On a successful call, the server responds with HTTP status 200 OK, and a body with the full STX object:

Response
{
"object": "smart.transactions",
"id": "STX_...",
// ...
}

Start the Checkout Wizard

The easiest way to start the checkout is to by entering the URL in the address line of your browser. You find this URL in checkout_links. url_checkout. Below is an example of the Checkout:

images/download/attachments/76289137/Checkout_Wizard.png

For example, you can:

  • display the checkout URL (url_checkout) in the customer's browser;

  • send it to your customer in an e-mail, a chat message, or a Text / SMS.

A Smart Transaction represents an order, and can only be used one time. It is not an offer, that can be used repeatedly, or for more than one customer.

Example:

{
"object": "smart.transactions",
"id": "STX_XXX2",
// ...
"checkout_links": {
"url_checkout": "https://checkout-dev.secuconnect.com?stx=STX_3XXXA2&server=nw",
// ...
},
// ...
}

The URL "checkout_links": { "url_checkout": is used to start the checkout. It contains the Smart Transaction ID.

Fullscreen Checkout

You can use HTML like this to start the checkout in the same browser window.

<a href="https://...">Check out now!</a>

Please replace the content of the href attribute with the URL of your created STX.

Opening the link will reveal the checkout.

iFrame Checkout

You can also use the link in an iframe. For instance to show it in a layer.

Please replace replace the content of the src attribute with the URL of your created STX.

<iframe src="https//..." .../>

Please replace replace the content of the src attribute with the URL of your created STX.

Sometimes the Checkout Wizard will have to leave the iframe in order to support checks for credit card payment, or to support certain browsers. Return URLs will open full screen. (refer to the reference for more information on return URLs).

Die eingeschlossene Seite konnte nicht gefunden werden.

Advanced Parameters

Fehler beim Ausführen des Makros 'include'

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

Use the secuconnect SDKs

Fehler beim Ausführen des Makros 'include'

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

Reference

Smart Transaction (STX) Definition

A smart transaction (short: STX) is is based on a payment transaction but offers additional features. STX are initiated via the secuconnect API. Smart Transactions feature, but are not limited to:

  1. Payment transactions

  2. Mixed Basket Transactions

  3. Tracking POS payments

  4. Perform loyalty transactions

  5. ZVT operations

A smart transaction does not necessarily contain a payment that needs to be handled by secupay. The smart transaction may contain a basket only (with information) from an electronic cash register that is used to initiate a card payment via electronic cash terminal. A smart transaction is always used with the Smart Checkout and with smart ZVT. It is part of a check-out process that may start with article selection in a store and end with the payment. In e-commerce, STX can also take over order fulfilment tasks (shipment, pick-up or service provision).

In order to create an STX, send a POST request to the Smart Transactions endpoint https://connect.secucard.com/api/v2/Smart/Transactions.

Initiating a transaction with a prepared STX offers protection against manipulation of the basket. It is therefore advised, to integrate with a combination of HTML and API or JavaScript an API.

Example Request STX with mixed basket

Request for STX with mixed basket
{
"is_demo":true,
"basket":{
"products":[
{
"id":0,
"item_type":"sub_transaction",
"desc":"Position 2 Order something",
"sum":999,
"quantity":1,
"priceOne":999,
"tax":19,
"reference_id":"1002",
"contract_id":"GCR_...",
"sub_basket":[
{
"id":1,
"parent":null,
"articleNumber":null,
"ean":null,
"desc":"cola 0.33 ltrs.",
"quantity":1,
"priceOne":500,
"tax":19,
"group":null,
"serialNumber":null,
"item_type":"article",
"reference_id":"1002/item1"
},
{
"id":2,
"parent":null,
"articleNumber":null,
"ean":null,
"desc":"cheese burger",
"quantity":1,
"priceOne":499,
"tax":19,
"group":null,
"serialNumber":null,
"item_type":"article",
"reference_id":"1002/item2"
},
{
"id":3,
"item_type":"stakeholder_payment",
"desc":"stakeholder_1",
"sum":5,
"reference_id":"1002/share2",
"contract_id":"GCR_..."
}
]
}
],
"texts":[
 
],
"type":"mixed"
},
"basket_info":{
"sum":999
},
"provider_contract":{
"id":"GCR_..."
},
"last_visited_page":"checkin_page",
"order_option":"shipping"
}

Example response Smart Transaction with mixed basket

Response STX with url_checkout
{
"object":"smart.transactions",
"id":"STX_...",
"merchant":{
"object":"general.merchants",
"id":"MRC_...",
"companyname":"Test GmbH"
},
"provider_contract":{
"object":"general.contracts",
"id":"GCR_..."
},
"contract":{
"object":"general.contracts",
"id":"GCR_..."
},
"transactions":[
 
],
"created":"2019-05-31T11:44:54+02:00",
"updated":"2019-05-31T11:44:54+02:00",
"status":"created",
"transactionRef":null,
"merchantRef":null,
"basket":{
"products":[
{
"item_type":"sub_transaction",
"desc":"Position 2 Order something",
"sum":999,
"reference_id":"1002",
"contract_id":"GCR_...",
"sub_basket":[
{
"id":1,
"parent":null,
"articleNumber":null,
"ean":null,
"desc":"cola 0.33 ltrs.",
"quantity":1,
"priceOne":500,
"tax":19,
"group":null,
"serialNumber":null,
"item_type":"article",
"reference_id":"1002/item1"
},
{
"id":2,
"parent":null,
"articleNumber":null,
"ean":null,
"desc":"cheese burger",
"quantity":1,
"priceOne":499,
"tax":19,
"group":null,
"serialNumber":null,
"item_type":"article",
"reference_id":"1002/item2"
},
{
"item_type":"stakeholder_payment",
"desc":"stakeholder_1",
"sum":5,
"reference_id":"1002/share2",
"contract_id":"GCR_..."
}
]
}
],
"texts":[
 
],
"type":"mixed"
},
"basket_info":{
"sum":999,
"gratuity":null,
"currency":"EUR"
},
"order_option":"shipping",
"last_visited_page":"checkin_page",
"is_demo":true,
"checkout_links":{
"url_checkout":"https://iframe-dev.secupay-ag.de?stx=STX_....&server=dev6"
},
"idents":null
}

Parameters Explained

Parameter

Description

Notes

"merchant":

Includes data about the Merchant e.g. name and ID

"contract":{

Contract that the Smart Transaction belongs to.

Main payment transaction is also associated with the contract.

"provider_contract":

Smart Checkout Provider.

Optional. Will be set by default.

"status":

Shows the current status of a smart transaction.

possible values: created, processing, approved, pending, shipped, received.

"checkout_links":{

Contains URL used to start the checkout.

Can be shared with a customer.

"transactions":[

Contains list of payment transactions.

Needed for getting the status of the payment transactions.

"transactionRef":

Used as a purpose for transaction with mixed baskets.

Optional. Default Payment transaction for smart transaction

"merchantRef":

Can be filled freely for identification.

Optional.

"basket_info":{

Contains sum: Total of all items (incl. sub-baskets).

order_option":

Default: shipping, can be collection for click and collect.

Mandatory

"is_demo":

Parameter that defines whether the transaction is simulated.

Mandatory.

Accessing STX via Browser

Using the URL returned in the response url_checkout": the smart transaction can be started inside a web browser.

The URL that is returned is only valid for one purchase offer.

images/download/attachments/81136862/Checkout_Wizard.png

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.

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.

(...)