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.