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.
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:
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.) |
|
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:
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:
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.
See Also
Further information: