Create the Smart Transaction for Marketplaces

This guide is for a marketplace with a custom checkout. There are other guides for simple webshops or e-commerce platforms. And there are also guides for our Smart Checkout.

Prerequisites

As a prerequisite, you should have read and understand:

Create a Smart Transaction

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

In contrast to webshops, you must pass a mixed basket with sub-baskets per merchant and stakeholder payments for the marketplace fees.

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_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
},
"provider_contract": {
"id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8"
},
"customer": {
"contact": {
"forename": "Max",
"surname": "Mustermann",
"phone": "+49 555 5555555",
"mobile": "+49 177 5555555",
"address": {
"street": "Musterstr.",
"street_number": "55 a",
"additional_address_data": "Whg. 203",
"postal_code": "09123",
"city": "Musterstadt",
"country": "DE"
},
"email": "max@example.net",
"dob": "1980-01-01"
}
},
"intent": "order",
"basket": {
"products": [
{
"item_type": "sub_transaction",
"desc": "Warenkorb Musterhändler Kaffee & Tee",
"sum": 3940,
"reference_id": "sb0",
"contract_id": "GCR_FN6CUOWY6VJKDHY0VIPHFM9344NKX7",
"sub_basket": [
{
"id": 1,
"articleNumber": 1,
"desc": "Kaffeepads Aromata 20 Stück",
"quantity": 2,
"priceOne": 1995,
"tax": 19
},
{
"id": 1000,
"item_type": "shipping",
"name": "Standardversand",
"quantity": 1,
"priceOne": 450,
"tax": 19
},
{
"item_type": "stakeholder_payment",
"desc": "Marktplatzgebühr",
"sum": 80,
"reference_id": "fee",
"contract_id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
}
]
},
{
"item_type": "sub_transaction",
"desc": "Warenkorb Musterhändler Einrichtung",
"sum": 3345,
"reference_id": "sb1",
"contract_id": "GCR_G8GOXJU27Z4JO9XONAH8ANLSF9OO30",
"sub_basket": [
{
"id": 1,
"articleNumber": 1,
"desc": "Magnettafel 70x50 cm",
"quantity": 1,
"priceOne": 2995,
"tax": 19
},
{
"id": 1000,
"item_type": "shipping",
"name": "Standardversand",
"quantity": 1,
"priceOne": 350,
"tax": 19
},
{
"item_type": "stakeholder_payment",
"desc": "Marktplatzgebühr",
"sum": 70,
"reference_id": "fee",
"contract_id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
}
]
}
]
},
"basket_info": {
"sum": 7285,
"currency": "EUR"
},
"delivery_options": {
"type": "shipping"
},
"payment_context": {
"auto_capture": true
}
}

This creates a demo transaction with two sub-baskets for two of the markektplace's suppliers. The marketplace earns a fee of €1.50. The auto_capture setting saves an additional API call, if it fits the flow.

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

Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
"object": "smart.transactions",
"id": "STX_3823Y85JF2P6BZS5C7TH6DTSGKUEA2",
"merchant": {
"object": "general.merchants",
"id": "MRC_SP02GWXS3FVVX0MFN2F95BN9F8SCE2",
"companyname": "Mustermarktplatz GmbH"
},
"provider_contract": {
"object": "general.contracts",
"id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8"
},
"contract": {
"object": "general.contracts",
"id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
},
"customer": {
"object": "payment.customers",
"id": "PCU_WAD6FUDZH2P6BGR48A2UV78BGRDAAJ",
"contact": {
"name": "Max Mustermann",
"forename": "Max",
"surname": "Mustermann",
"dob": "1980-01-01T00:00:00+00:00",
"email": "max@example.net",
"phone": "+495555555555",
"mobile": "+491775555555",
"address": {
"street": "Musterstr.",
"street_number": "55a",
"additional_address_data": "Whg. 203",
"postal_code": "09123",
"city": "Musterstadt",
"country": "DE"
}
}
},
"transactions": [],
"created": "2023-08-03T14:01:14+02:00",
"status": "created",
"intent": "order",
"basket": {
"products": [
{
"item_type": "sub_transaction",
"desc": "Warenkorb Musterhändler Kaffee & Tee",
"reference_id": "sb0",
"contract_id": "GCR_FN6CUOWY6VJKDHY0VIPHFM9344NKX7",
"sum": 3940,
"sub_basket": [
{
"id": 1,
"item_type": "article",
"desc": "Kaffeepads Aromata 50 Stück",
"articleNumber": "1",
"quantity": 2,
"priceOne": 1995,
"tax": 19
},
{
"id": 1000,
"item_type": "shipping",
"desc": "Standardversand",
"quantity": 1,
"priceOne": 450,
"tax": 19
},
{
"item_type": "stakeholder_payment",
"desc": "Marktplatzgebühr",
"reference_id": "fee",
"contract_id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2",
"sum": 80
}
]
},
{
"item_type": "sub_transaction",
"desc": "Warenkorb Musterhändler Einrichtung",
"sum": 3345,
"reference_id": "sb1",
"contract_id": "GCR_G8GOXJU27Z4JO9XONAH8ANLSF9OO30",
"sub_basket": [
{
"id": 1,
"articleNumber": 1,
"desc": "Magnettafel 70x50 cm",
"quantity": 1,
"priceOne": 2995,
"tax": 19
},
{
"id": 1000,
"item_type": "shipping",
"name": "Standardversand",
"quantity": 1,
"priceOne": 350,
"tax": 19
},
{
"item_type": "stakeholder_payment",
"desc": "Marktplatzgebühr",
"sum": 70,
"reference_id": "fee",
"contract_id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
}
]
}
],
"type": "mixed"
},
"basket_info": {
"sum": 7285,
"currency": "EUR"
},
"is_demo": true,
"delivery_options": {
"type": "shipping"
},
"payment_context": {
"auto_capture": true,
"merchant_initiated": false,
"accrual": false
},
"checkout_links": {
"url_checkout": "https://checkout-dev.secuconnect.com?wizardFlow=checkout&stx=STX_3823Y85JF2P6BZS5C7TH6DTSGKUEA2&viewMode=fullscreen&basketDisplay=full&server=dev6"
}
}

Important fields are:

Field

Type

Meaning

id

string

The object ID of the new Smart Transaction.

status

string

The status of the Smart Transaction.

Most interesting is the ID of the Smart Transaction. Your application needs it for subsequent calls.

For further explanation of the fields, see our API Reference: link