Create the Smart Transaction for Platforms

This guide is for e-commerce platforms. There are other guides for webshops, or internet marketplaces.

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 also pass 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_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:

  • 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

Unique item ID.

item_type

string

Optionally the function of the item:

  • "article" for the goods;

  • "coupons" for vouchers;

  • "shipping" for shipping fees;

  • "stakeholder_payment" for marketplace fees, or the like.

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:

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": "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.