Create a Smart Transaction with Minimal Data

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

Request

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secupay-ag.de
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "is_demo": true,
    "contract": {
        "id": "GCR_9OIH9JOL8KIV5PFJBEOS2NN8TCM1DF"
    },
    "device_source": {
        "id": "SDV_2YJDXYESB2YBHECVB5GQGSYPNM8UA6"
    },
    "customer": {
        "contact": {
            "salutation": "Mr.",
            "title": "Dr.",
            "forename": "Max",
            "surname": "Mustermann",
            "address": {
                "street": "Musterstr.",
                "street_number": "25 b",
                "additional_address_data": "Whg. 123",
                "postal_code": "99999",
                "city": "Musterstadt",
                "country": "DE"
            },
            "email": "max123@example.org",
            "phone": "+49 555 5555555",
            "mobile": "+49 177 5555555",
            "dob": "1901-02-03"
        }
    },
    "intent": "sale",
    "basket_info": {
        "sum": 0,
        "currency": "EUR"
    }
}

These three things are special:

The contract ID is only needed in e-commerce, but not in a POS device context.
The source device ID is only needed for loyalty in e-commerce.
The card number. It could also be set later, using PUT /api/v2/Smart/Transactions/STX_WHCJCB3SD2NSZZ73E33NP3TJJ4RKA2.

You could also set the Payment Customer ID in order to reuse it.

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

Reponse

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_KJXJDUN542NR3WMRHRVU5WWM6ZQEA2",
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8",
        "companyname": "Secupay Test-Shop"
    },
    "contract": {
        "object": "general.contracts",
        "id": "GCR_9OIH9JOL8KIV5PFJBEOS2NN8TCM1DF"
    },
    "device_source": {
        "object": "smart.devices",
        "id": "SDV_2YJDXYESB2YBHECVB5GQGSYPNM8UA6"
    },
    "customer": {
        "object": "payment.customers",
        "id": "PCU_24XQFBSAS2NSZZPUYR9F20330GX6AZ",
        "contact": {
            "forename": "Max",
            "surname": "Mustermann",
            "name": "Max Mustermann",
            "salutation": "Mr.",
            "title": "Dr.",
            "address": {
                "street": "Musterstr.",
                "street_number": "25 b",
                "additional_address_data": "Whg. 123",
                "postal_code": "99999",
                "city": "Musterstadt",
                "country": "DE"
            },
            "email": "max123@example.org",
            "mobile": "+491775555555",
            "phone": "+495555555555",
            "dob": "1901-02-03T00:00:00+01:00"
        }
    },
    "transactions": [],
    "created": "2020-09-22T13:53:44+02:00",
    "status": "created",
    // ...
    "basket": {
        "products": [],
        // ...
    },
    "basket_info": {
        "sum": 0,
        "currency": "EUR",
        // ...
    },
    "is_demo": true,
    // ...
}

When you authenticate as device, the merchant is resolved automatically.

Update the Smart Transaction with Card and Basket

You can change the Smart Transaction as long as the payment has not been executed. The endpoint for doing this is PUT /api/v2/Smart/Transactions/{id}.

In our example we will:

update the basket (basket/products);
add a secucard (idents);
add a customer reference (merchantRef);
add an order ID (transactionRef).

Example request:

Request

PUT /api/v2/Smart/Transactions/STX_KJXJDUN542NR3WMRHRVU5WWM6ZQEA2 HTTP/1.1
Host: connect-testing.secupay-ag.de
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    // ...
    "idents": [
        {
            "type": "card",
            "value": "9276004429942845"
        }
    ],
    "basket": {
        "products": [
            {
                "id": 1,
                "parent": null,
                "articleNumber": 30037,
                "ean": null,
                "desc": "Sandwich Romano",
                "quantity": 1,
                "priceOne": 349,
                "tax": 7
            },
            {
                "id": 2,
                "parent": null,
                "articleNumber": 30200,
                "ean": null,
                "desc": "Fruit salad, small bowl",
                "quantity": 1,
                "priceOne": 249,
                "tax": 7
            },
            {
                "id": 3,
                "parent": null,
                "articleNumber": 51,
                "ean": "4999012345678",
                "desc": "Water, mildly sprinkling, 0.25 ltr.",
                "quantity": 2,
                "priceOne": 99,
                "tax": 19           
            }
        ]
    },
    "basket_info": {
        "sum": 796,
        "currency": "EUR"
    },
    "merchantRef": "customer nr. 123",
    "transactionRef": "order nr. 123",
    // ...
}

This creates a Smart Transaction about €7.96. The articles have gross unit prices of €3.49, €2.49, and €0.99.

Monetary amounts are expressed in the smallest currency unit (e. g. Euro Cent). The same applies to the card details in the response.

Successful response:

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_KJXJDUN542NR3WMRHRVU5WWM6ZQEA2",
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8",
        "companyname": "Secupay Test-Shop"
    },
    "contract": {
        "object": "general.contracts",
        "id": "GCR_9OIH9JOL8KIV5PFJBEOS2NN8TCM1DF"
    },
    "device_source": {
        "object": "smart.devices",
        "id": "SDV_2YJDXYESB2YBHECVB5GQGSYPNM8UA6"
    },
    "created": "2020-09-17T09:18:14+02:00",
    "status": "created",
    // ...
    "merchantRef": "customer nr. 123",
    "transactionRef": "order nr. 123",
    "basket": {
        "products": [
            {
                "id": 1,
                "parent": null,
                "articleNumber": 30037,
                "ean": null,
                "desc": "Sandwich Romano",
                "quantity": 1,
                "priceOne": 349,
                "tax": 7,
                // ...
            },
            {
                "id": 2,
                "parent": null,
                "articleNumber": 30200,
                "ean": null,
                "desc": "Fruit salad, small bowl",
                "quantity": 1,
                "priceOne": 249,
                "tax": 7,
                // ...
            },
            {
                "id": 3,
                "parent": null,
                "articleNumber": 51,
                "ean": "4999012345678",
                "desc": "Water, mildly sprinkling, 0.25 ltr.",
                "quantity": 2,
                "priceOne": 99,
                "tax": 19,
                // ...              
            }
        ],
        // ...
    },
    "basket_info": {
        "sum": 796,
        "currency": "EUR",
        // ...
    },
    "idents": [
        {
            "object": "smart.idents",
            "id": "smi_1",
            "prefix": "9276",
            "name": "secucard Kundenkarte",
            "type": "card",
            "value": "9276004429942845",
            "valid": true,
            "merchantcard": {
                "object": "loyalty.merchantcards",
                "id": "MCD_2RXTNXPRM2YG9922UMBHHAEWEGN6AJ",
                "merchant": {
                    "object": "general.merchants",
                    "id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8"
                },
                "created_for_merchant": {
                    "object": "general.merchants",
                    "id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8"
                },
                "card": {
                    "object": "loyalty.cards",
                    "id": "CRD_2U7MTNAMM3PMBPAB50C9G2AEHA9GPJ",
                    "cardnumber": "9276004429942845",
                    "created": "2015-09-28T16:01:20+02:00"
                },
                "cardgroup": {
                    "object": "loyalty.cardgroups",
                    "id": "CRG_GO7GQ6DHW3TJYGDF64WD16PUIDHQ8Y",
                    "display_name": "Geschenkgutschein",
                    "display_name_raw": "Geschenkgutschein",
                    "stock_warn_limit": 0,
                    "picture": "https://connect.secucard.com/ds_g/8e79737df1e2513db48908b342c3cc436edf501a"
                },
                "created_for_store": {
                    "object": "general.stores",
                    "id": "STO_2ZCZRU9V6U8QA7B49K94667UP6C4PJ"
                },
                "customer": {
                    "object": "loyalty.customers",
                    "id": "CUS_2YBREKK0A2MNAXJ752TSDD9DH3PKAJ",
                    "contact": {
                        "name": "Max Mustermann",
                        "forename": "Max",
                        "surname": "Mustermann",
                        "dob": "1981-02-14T00:00:00+00:00"
                    },
                    "created": "2018-05-03T10:14:06+02:00",
                    "consent_for_communication": true
                },
                "is_base_card": true,
                "points": 0,
                "cash_balance": 500,
                "bonus_balance": 0,
                "balance": 500,
                "last_usage": "2020-03-17T07:22:36+01:00",
                "last_charge": "2019-12-10T12:56:08+01:00",
                "stock_status": "active",
                "lock_status": "unlocked",
                "passcode": 0,
                "expiry_date": null
            },
            "customer": {
                "object": "loyalty.customers",
                "id": "CUS_2YBREKK0A2MNAXJ752TSDD9DH3PKAJ",
                "contact": {
                    "name": "Max Mustermann",
                    "forename": "Max",
                    "surname": "Mustermann",
                    "dob": "2018-02-14T00:00:00+00:00"
                },
                "created": "2018-05-03T10:14:06+02:00",
                "consent_for_communication": true
            }
        }
    ],
    "is_demo": true,
    // ...
}

As you see, the secucard is recognized.

Here a subsection taken from the Merchant Card details:

{
    // ...
    "points": 12,
    "cash_balance": 500,
    "bonus_balance": 0,
    "balance": 500,
    "last_usage": "2020-03-17T07:22:36+01:00",
    "last_charge": "2019-12-10T12:56:08+01:00",
    "stock_status": "active",
    "lock_status": "unlocked",
    "passcode": 0
}

And here the explanation:

Field	Description
`cash_balance`	Money credit reveived for payment in the smaller currency unit
`bonus_balance`	Money credit received as bonus for a former buy in the smaller currency unit
`balance`	Total money credit in the maller currency unit. Cash and bonus balance can be spent the same time.
`stock_status`	Life cycle of the card: `stored` `active` `inactive`
`lock_status`	`locked` `unlocked`
`passcode`	Whether you have to check the passcode before the card is used: `0`: passcode check is not needed; `1`: passcode check is needed.

Note: Monetary units are expressed in the smaller currency unit.

This means, applied to our example:

There is €5.00 of money balance received for a payment.
There is no money balance received as a bonus for a former buy.
The buyer can pay €5.00 using this card.
There are also a few bonus points.
The card can be used. It is active, and there are no locks.
You don't need to bother the buyer with the card passcode (card security code).

The above means, you can use the card balance for the next payment. But the customer can also save it for later. Read more on this in the section about how to carry out the payment.

Create the Same Smart Transaction at Once

You can also create the Smart Transaction with the basket and the secucard from the beginning. It is the same endpoint POST /api/v2/Smart/Transactions. The additional parameters are the same as in the update request in the section before.

Request

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secupay-ag.de
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "is_demo": true,
    "idents": [
        {
            "type": "card",
            "value": "9276004429942845"
        }
    ],
    "contract": {
        "id": "GCR_9OIH9JOL8KIV5PFJBEOS2NN8TCM1DF"
    },
    "device_source": {
        "id": "SDV_2YJDXYESB2YBHECVB5GQGSYPNM8UA6"
    },
    "intent": "sale",
    "basket": {
        "products": [
            {
                "id": 1,
                "parent": null,
                "articleNumber": 30037,
                "ean": null,
                "desc": "Sandwich Romano",
                "quantity": 1,
                "priceOne": 349,
                "tax": 7
            },
            {
                "id": 2,
                "parent": null,
                "articleNumber": 30200,
                "ean": null,
                "desc": "Fruit salad, small bowl",
                "quantity": 1,
                "priceOne": 249,
                "tax": 7
            },
            {
                "id": 3,
                "parent": null,
                "articleNumber": 51,
                "ean": "4999012345678",
                "desc": "Water, mildly sprinkling, 0.25 ltr.",
                "quantity": 2,
                "priceOne": 99,
                "tax": 19           
            }
        ]
    },
    "basket_info": {
        "sum": 796,
        "currency": "EUR"
    },
    "merchantRef": "customer nr. 123",
    "transactionRef": "order nr. 123"
}

This creates a Smart Transaction about €7.96. The articles have gross unit prices of €3.49, €2.49, and €0.99.

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

The outcome is, and the response looks, exactly like in the section before.