Create the 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.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "is_demo": true,
    "contract": {
        "id": "GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0"
    },
    "customer": {
        "contact": {
            "forename": "Lesley",
            "surname": "Mustermann",
            "phone": "+49 555 5555555",
            "mobile": "+49 177 5555555",
            "address": {
                "street": "Musterstr.",
                "street_number": "840",
                "additional_address_data": "App. 506",
                "postal_code": "09999",
                "city": "East Palmaside",
                "country": "DE"
            },
            "email": "Andrew37@example.org",
            "dob": "1965-12-31"
        }
    },
    "intent": "sale",
    "basket": {
        "products": [
            {
                "item_type": "sub_transaction",
                "desc": "Order for Muster-Elektrogeräte GmbH",
                "sum": 9350,
                "reference_id": "1002",
                "contract_id": "GCR_ZPMJGRH4SU3X0H3Y3WYB69XVXAG8PJ",
                "sub_basket": [
                    {
                        "id": 1,
                        "articleNumber": 1,
                        "desc": "Coffee maker with remote control",
                        "quantity": 2,
                        "priceOne": 5000,
                        "tax": 19
                    },
                    {
                        "id": 2,
                        "item_type": "coupon",
                        "desc": "Coupon €10",
                        "quantity": 1,
                        "priceOne": 1000,
                        "tax": 19
                    },
                    {
                        "id": 1000,
                        "item_type": "shipping",
                        "name": "Standard delivery 2-3 days",
                        "quantity": 1,
                        "priceOne": 350,
                        "tax": "19"
                    },
                    {
                        "item_type": "stakeholder_payment",
                        "desc": "Marketplace fee",
                        "sum": 150,
                        "reference_id": "fee",
                        "contract_id": "GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0"
                    }
                ]
            }
        ]
    },
    "basket_info": {
        "sum": 9350,
        "currency": "EUR"
    },
    "payment_context": {
        "auto_capture": true
    }
} 

This creates a Smart Transaction with an amount of €95.00.

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

The most important fields are:

Field	Type	Meaning
`is_demo`	`boolean`	Optional flag for demo mode. Defaults to `false` (productive transaction).
`contract/id`	`string`	Contract ID (`GCR_xxx`) of the marketplace.
`customer`	`object`	Optional customer ID or details. Explained in another section.
`intent`	`string`	A Smart Transaction can have one of two basic operating modes, called `intent`: `order` for purchase orders; `sale` for payment without assuming a contract type. An order requires an agreement about shipping or collection. The button for the conclosure has a different label (Buy Now! instead of Pay Now!). Incoming orders are found in SecuOffice under Orders » Completed. Payments can be used for donation, crowd funding, or reservation fees, to name a few examples.
`basket`	`object`	Optional basket. Explained in another section.
`basket_info`	`object`	Amount to pay. (Amongst other details not of interest here.)
`basket_info/sum`	`int`	Amount to pay in the smallest currency unit. For instance, `9350` in combination with `EUR` mean €93.50.
`basket_info/currency`	`string`	ISO three-letter currency code. Defaults to `EUR`.
`payment_context`	`object`	Optional payment settings.
`payment_context/auto_capture`	`boolean`	Optional flag for auto-capture. Defaults to `false` (explicit capture). Explained in another section.

If everything is fine, the API responds with 200 OK, and the object representation:

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_2UYAHWYC32X2GT37V32E8BPRNUA2A3",
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_WVHJQFQ4JNVYNG5B55TYK748ZCHQP8",
        "companyname": "Secupay Test-Shop"
    },
    "contract": {
        "object": "general.contracts",
        "id": "GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0"
    },
    "customer": {
        "object": "payment.customers",
        "id": "PCU_3J7GCMPPE2X2GT37V32E8BPRNUA2AW",
        "contact": {
            "forename": "Lesley",
            "surname": "Mustermann",
            "address": {
                "street": "Musterstr.",
                "street_number": "840",
                "additional_address_data": "App. 506",
                "postal_code": "09999",
                "city": "East Palmaside",
                "country": "DE"
            },
            "email": "Andrew37@example.org"
            "phone": "+49 555 5555555",
            "mobile": "+49 177 5555555",
            "dob": "1965-12-31T00:00:00+01:00"
        }
    },
    // ...
    "created": "2021-03-16T18:20:15+01:00",
    "status": "created",
    // ...
    "intent": "sale",
    "basket": {
        "products": [{
            "item_type": "sub_transaction",
            "desc": "Order for Muster-Elektrogeräte GmbH",
            "reference_id": "1002",
            "contract_id": "GCR_ZPMJGRH4SU3X0H3Y3WYB69XVXAG8PJ",
            "sum": 9500,
            "sub_basket": [{
                "id": 1,
                "parent": null,
                "item_type": "article",
                "desc": "Coffee maker with remote control",
                "articleNumber": "1",
                "ean": "",
                "quantity": 2,
                "priceOne": 5000,
                "tax": 19,
                "reference_id": null,
                "group": []
            }, {
                "id": 2,
                "parent": null,
                "item_type": "coupon",
                "desc": "Coupon \u20ac10",
                "articleNumber": "",
                "ean": "",
                "quantity": 1,
                "priceOne": 1000,
                "tax": 19,
                "reference_id": null,
                "group": []
            }, {
                "id": 1000,
                "parent": null,
                "item_type": "shipping",
                "desc": "Standard delivery 2-3 days",
                "articleNumber": "",
                "ean": "",
                "quantity": 1,
                "priceOne": 350,
                "tax": "19",
                "reference_id": null,
                "group": []
            }, {
                "item_type": "stakeholder_payment",
                "desc": "Marketplace fee",
                "reference_id": "fee",
                "contract_id": "GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0",
                "sum": 150
            }]
        }],
        "type": "mixed"
        // ...
    },
    "basket_info": {
        "sum": 9350,
        // ...
        "currency": "EUR"
    },
    "is_demo": true,
    // ...
    "payment_context": {
        "auto_capture": true,
        "payment_methods": null
    },
    // ...
} 

Our system added some fields. The most important fields are:

Field	Type	Meaning
`id`	`string`	Smart Transaction ID (`STX_xxx`). Needed to read or update the Smart Transaction, to authorise or capture the payment, and signalise delivery.
`merchant`	`object`	Merchant details, here those of the marketplace.
`customer`	`object`	Customer details.
`customer/id`	`string`	Payment Customer ID (`PCU_xxx`). Can be used to reuse the same customer data.
`status`	`string`	Transaction status. The status flow is explained in another section.