Create the Smart Transaction for Webshops

This guide is for a webshop. There are distinct guides for internet marketplaces, or e-commerce platforms.

Prerequisites

As a prerequisite, you should understand:

Create 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.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"is_demo": true,
"intent": "sale",
"contract": {
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
"customer": {
       "contact": {
"forename": "Max",
"surname": "Mustermann",
"salutation": "Mr.",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"additional_address_data": "Whg. 202",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE"
},
"email": "max@example.net",
"mobile": "+491775555555",
"phone": "+495555555555"
}
  },
  "merchantRef": "K/01234",
  "transactionRef": "B/001234567",
   "basket": {
"products": [
{
"id": 1,
"articleNumber": 30037,
"ean": "4999012345678",
"desc": "Höhenverstellbarer Schreibtisch",
"quantity": 1,
"priceOne": 49800,
"tax": 19
},
{
"id": 2,
"item_type": "coupon",
"desc": "Coupon 20 €",
"quantity": 1,
"priceOne": 2000,
"tax": 19
},
{
"id": 3,
"item_type": "shipping",
"desc": "Versand Spedition",
"quantity": 1,
"priceOne": 3500,
"tax": 19
}
]
},
"basket_info": {
"sum": 51300,
"currency": "EUR"
},
  "payment_context": {
"auto_capture": true
}
}

This creates a demo transaction to sell a desk. The total amount is €513.00. The auto_capture setting saves an additional API call, if it fits the flow.

Request details:

Field

Type

Meaning

is_demo

boolean

Optional. Whether the transaction is a demo transaction:

  • true for demo transactions;

  • false for productive transactions.

Defaults to false, productive transaction.

intent

string

The intent of the transaction. In our case always sale.

contract

object

The contract ID of the merchant ("id": "GCR_..."). You receive this ID during onboarding.

customer

object

The customer, either its ID or its details. (See details below.)

merchantRef

string

Optional. The merchant's own customer ID. This can be helpful to trace back the customer account on your site.

transactionRef

string

Optional. The merchant's own order ID. This can be helpful to trace back the order on your site. It is also used for the purpose line at the bank statements.

basket

object

Optional basket details, like article positions or shipping fee. (See details below.)

basket_info

object

The basket meta data, like currency and total. (See details below.)

application_context

object

Optional application context for Smart Checkout integration, like return URLs. (Described for Smart Checkout; see link below.)

payment_context

object

Control payment context. (See details below.)

Details of the customer object:

Field

Type

Meaning

id

string

The customer ID ("PCU_..."), if not contact.

contact

object

The customer contact details. (See details directly below.)

Details of the contact object (inside customer):

Field

Type

Meaning

company_name

string

Optional company name.

forename

string

First name of the person.

surname

string

Last name of the person.

salutation

string

Optional salutation of the person.

address

object

Optional postal address. (See details below.)

email

string

Email address.

phone

string

Optional landline number.

mobile

string

Optional mobile phone number.

date_of_birth

string

Optional date of birth. (ISO 8601 date like "2023-02-28".)

Details of the address object (inside contact):

Field

Type

Meaning

street

string

Street, or street with house number.

street_number

string

Optional house number.

additional_address_data

string

Optional second address line, for apartment number, etc.

postal_code

string

ZIP code.

city

string

City or town.

country

string

Country. (ISO 3166 two letter country code like "DE".)

Details of the basket object:

Field

Type

Meaning

products

object[]

Article positions, shipping fee, etc.

Details of the product objects:

Field

Type

Meaning

id

int

Item ID.

item_type

string

Optionally the function of the item:

  • "article" for the goods;

  • "coupons" for vouchers;

  • "shipping" for shipping fees.

Coupons are considered with the reverse value in the total. For instance one coupon having "priceOne": 500 reduces the total by 5 EUR, or another currency.

There exist more item types that are introduced where relevant.

articleNumber

int

Optional article number of the merchant often called SKU number.

ean

string

Optional European Article Number (EAN) or Global Trade Identification Number (GTIN).

desc

string

Short text that describes the article (article name, perhaps size), coupon or shipping fee.

quantity

int

Quantity.

priceOne

int

Gross unit price in the smallest currency unit.

tax

int

Optional V. A. T rate of that article, coupon, or shipping fee.

Details of the basket_info object:

Field

Type

Meaning

sum

int

Total sum of the entire transaction in the smallest currency unit.

currency

string

Currency of the entire transaction. (ISO 4217 three-letter code like "EUR" or "USD".)

Details of the payment_context object (incomplete):

Field

Type

Meaning

auto_capture

boolean

Whether the amount is captured automatically after successful authorisation. This saves an additional API call when the payment process is also the order confirmation, for instance. It controls also whether Smart Checkout returns with an authorised transaction or already captures it.

Defaults to false, needs explicit capture.

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

Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"merchant": {
"object": "general.merchants",
"id": "MRC_AZS7P6FTNTC6NK0QWFDBREW94ZY2O7",
"companyname": "Smart Checkout Testmerchant 8"
},
"provider_contract": {
"object": "general.contracts",
"id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8"
},
"contract": {
"object": "general.contracts",
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
"customer": {
"object": "payment.customers",
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ",
"contact": {
"forename": "Max",
"surname": "Mustermann",
"name": "Max Mustermann",
"salutation": "Mr.",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"additional_address_data": "Whg. 202",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE"
},
"email": "max@example.net",
"mobile": "+491775555555",
"phone": "+495555555555"
}
},
"transactions": [],
"created": "2020-03-27T10:55:23+01:00",
"status": "created",
"merchantRef": "K/01234",
  "transactionRef": "B/001234567",
  "intent": "sale",
"basket": {
"products": [
{
"id": 1,
"parent": null,
"item_type": "article",
"desc": "Höhenverstellbarer Schreibtisch",
               "articleNumber": 30037,
"ean": "4999012345678",
"quantity": 1,
"priceOne": 49800,
"tax": 19,
"reference_id": null,
"group": []
          },
{
"id": 2,
"parent": null,
              "item_type": "coupon",
"desc": "Coupon 20 €",
"articleNumber": "",
"ean": "",
              "quantity": 1,
"priceOne": 2000,
"tax": 19,
"reference_id": null,
"group": []
          },
{
"id": 3,
"parent": null,
              "item_type": "shipping",
"desc": "Versand Spedition",
"articleNumber": "",
"ean": "",
               "quantity": 1,
"priceOne": 3500,
"tax": 19,
"reference_id": null,
"group": []
            }
],
"type": "default"
  },
"basket_info": {
"sum": 51300,
"currency": "EUR"
},
  "is_demo": true,
// ...
"payment_context": {
"auto_capture": true,
"payment_methods": null,
"merchant_initiated": false,
"accrual": false,
"creditcard_schemes": [
"mastercard",
"visa",
"american express"
]
},
// ...
}

The system behind the secuconnect API has added more data. The most interesting are:

Field

Type

Meaning

id

string

The ID of the new Smart Transaction object ("STX_...").

status

string

The status of the Smart Transaction.

The status is "created" so far. The Smart Transaction ID is needed for the subsequent API calls, if you build you custom checkout.