Integration Guide

To make a payment we need a Smart Transaction.

The API endpoint to create a Smart Transaction is POST /api/v2/Smart/Transactions:

Request

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secuconnect.com
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "intent": "sale",
    "basket": {
        "products": [
            {
                "id": 1,
                "item_type": "article",
                "desc": "BRÖTCHENANGEBOT 8 Stück",
                "articleNumber": "70000",
                "ean": null,
                "quantity": 1,
                "priceOne": 1,
                "tax": 7,
                "group": [
                    {
                        "id": "1",
                        "desc": "Backwaren",
                        "level": 1
                    },
                    {
                        "id": "2",
                        "desc": "Brötchen",
                        "level": 2
                    }
                ]
            }
        ],
    },
    "basket_info": {
        "sum": 1,
        "currency": "EUR"
    },
    "merchantRef": "Kundennr. 101",
    "transactionRef": "Belegnr. 55501",
}

This creates a Smart Transaction about €0.01.

Monetary amounts are expressed in the smallest currency unit (e. g. Euro Cent).

These are the parameters:

Field	Type	Details
`intent`	`string`	Always `sale` for our purpose
`basket`	`object`	Optional simple or mixed basket (here a simple one)
`basket/products`	`array`	Array with the basket items
`basket_info`	`object`	Summary of the basket
`basket_info/sum`	`int`	Basket total (must equal the sum of all item totals)
`basket_info/currency`	`string`	ISO 4217 currency code such as `EUR`, `CHF`, `GBP` or `USD`.
`merchantRef`	`string`	Optional customer reference by the merchant
`transactionRef`	`string`	Optional transaction reference by the merchant

The basket items within basket/products in more detail:

Field	Type	Details
`id`	`string`	Unique identifier for the position
`item_type`	`string`	Always `article` or `coupon` here. Coupons lower the basket total instead of increasing it. There are more item types in conjunction with feature not explained in this guide.
`desc`	`string`	Article name
`articleNumber`	`string`	Optional merchant article number
`ean`	`string`	Optional manufacturer EAN / GTIN of the product
`quantity`	`int`	Number of items sold
`priceOne`	`int`	Gross unit price of this article (the price of one piece including taxes)
`tax`	`int`	Tax rate in percent
`group`	`array`	Optional product groups

If everything is fine, the API responds with 200 OK, and the representation of the newly created Smart Transaction:

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_3HXQQBSVK2XWNAX7ESCZH9NZY3YZAZ",
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_8GTCKFB97SR4GET4KGAB6Y59K4PGO8",
        "companyname": "Musterfirma GmbH"
    },
    "device_source": {
        "object": "smart.devices",
        "id": "SDV_2T23JN7KS2NVMPJ76SPZV9HGWXFHA2"
    },
    "created": "2021-02-25T08:47:25+01:00",
    "status": "created",
    // ...
    "merchantRef": "Kundennr. 101",
    "transactionRef": "Belegnr. 55501",
    "basket": {
        "products": [
            {
                "id": 1,
                "parent": null,
                "item_type": "article",
                "desc": "BRÖTCHENANGEBOT 8 Stück",
                "articleNumber": "70000",
                "ean": null,
                "quantity": 1,
                "priceOne": 1,
                "tax": 7,
                "reference_id": null,
                "group": [
                    {
                        "id": "1",
                        "desc": "Backwaren",
                        "level": 1
                    },
                    {
                        "id": "2",
                        "desc": "Brötchen",
                        "level": 2
                    }
                ]
            }
        ],
        "type": "default",
        "texts": []
    },
    "basket_info": {
        "sum": 1,
        "currency": "EUR",
        // ...
    },
    "is_demo": false,
    // ...
}

The new Smart Transaction has the initial status created. The API also adds some information about the merchant and the device.