Create the Smart Transaction for Platforms
This guide is for e-commerce platforms. There are other guides for webshops, or internet marketplaces.
Create a Smart Transaction
The API endpoint to create a Smart Transaction is POST /api/v2/Smart/Transactions.
In contrast to webshops, you must also pass stakeholder payments for the marketplace fees.
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"
:
"Markus"
,
"surname"
:
"Mustermann"
,
"phone"
:
"+49 555 5555555"
,
"mobile"
:
"+49 177 5555555"
,
"address"
: {
"street"
:
"Musterstr."
,
"street_number"
:
"12 b"
,
"additional_address_data"
:
"Whg. 202"
,
"postal_code"
:
"09999"
,
"city"
:
"Musterstadt"
,
"country"
:
"DE"
},
"email"
:
"markus@example.net"
,
"dob"
:
"1965-12-31"
}
},
"intent"
:
"sale"
,
"basket"
: {
"products"
: [
{
"id"
: 1,
"articleNumber"
: 1,
"desc"
:
"Coffee maker with remote control"
,
"quantity"
: 1,
"priceOne"
: 5000,
"tax"
: 19
},
{
"id"
: 1000,
"item_type"
:
"shipping"
,
"name"
:
"Standard delivery 2-3 days"
,
"quantity"
: 1,
"priceOne"
: 350,
"tax"
:
"19"
},
{
"item_type"
:
"stakeholder_payment"
,
"desc"
:
"Platform fee"
,
"sum"
: 161,
"reference_id"
:
"fee"
,
"contract_id"
:
"GCR_ZPMJGRH4SU3X0H3Y3WYB69XVXAG8PJ"
}
]
},
"basket_info"
: {
"sum"
: 5350,
"currency"
:
"EUR"
},
"payment_context"
: {
"auto_capture"
:
true
},
"application_context"
: {
"return_urls"
: {
"url_push"
:
"https://shop.example.org/PUSH?order=12345"
}
}
}
This creates a demo for a coffee maker about €53.50 including shipping cost. The platform earns a fee of €1.61. 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 |
Unique item ID. |
item_type |
string |
Optionally the function of the item:
Stakeholder payments do not influence the total at all. You can also have multiple stakeholder payments, for instance a marketplace fee, and an agency fee. 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. |
contract_id |
string |
Contract ID of the recipient of the stakeholder payment. |
reference_id |
string |
Optional unique handle to identify basket items later, for instance to trace back split Payment Transactions to . |
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, shipping fee or stakeholder payment. |
quantity |
int |
Quantity. |
priceOne |
int |
Gross unit price in the smaller 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 smaller 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 can 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. |
Since everthing is fine, the API responds with 200 OK:
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"
:
"Markus"
,
"surname"
:
"Mustermann"
,
"name"
:
"Markus Mustermann"
,
"phone"
:
"+49 555 5555555"
,
"mobile"
:
"+49 177 5555555"
,
"address"
: {
"street"
:
"Musterstr."
,
"street_number"
:
"12 b"
,
"additional_address_data"
:
"Whg. 202"
,
"postal_code"
:
"09999"
,
"city"
:
"Musterstadt"
,
"country"
:
"DE"
},
"email"
:
"markus@example.net"
,
"dob"
:
"1965-12-31T00:00:00+01:00"
}
},
// ...
"created"
:
"2021-03-16T18:20:15+01:00"
,
"status"
:
"created"
,
// ...
"intent"
:
"sale"
,
"basket"
: {
"products"
: [{
"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"
: 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"
:
"Platform fee"
,
"reference_id"
:
"fee"
,
"contract_id"
:
"GCR_ZPMJGRH4SU3X0H3Y3WYB69XVXAG8PJ"
,
"sum"
: 161
}],
// ...
},
"basket_info"
: {
"sum"
: 5350,
// ...
"currency"
:
"EUR"
},
"is_demo"
:
true
,
// ...
"payment_context"
: {
"auto_capture"
:
true
,
// ...
},
"application_context"
: {
"return_urls"
: {
"url_push"
:
"https://shop.example.org/PUSH?order=12345"
}
}
}
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: