This guide is for marketplaces with our Smart Checkout. There are other guides for simple webshops or e-commerce platforms. And there is also a guide to build your own custom checkout .

Prerequisites

Process Worflow

Using the API integration you need to care about four process participants:

  • your customer
  • your website
  • our secuconnect API
  • our Smart Checkout

Process outline:

The customer details can be requested by Smart Checkout, but can also be passed to the Smart Transaction in the beginning.

The payment authorisation can be more complex than you can see here. It can contain:

  • the selection of a payment method
  • to enter credit card details
  • to enter bank details and give a SEPA direct debit mandate
  • to make a 3-D Secure check for credit card payments, if requirede
  • to visit the PayPal payment page
  • to visit the klarna Sofort page
  • to visit the giropay page
  • to visit the eps page
  • to visit the easyCredit Ratenkauf page

Everything in the checkout process is managed by our Smart Checkout, and you don't need to care for the details.

If the final confirmation takes place in Smart Checkout, this step can be saved. This is controlled with the option payment_context/auto_capture in the Smart Transaction.

The additional steps to mark orders with invoice payments as shipped, or to respond on progress or problems, are only necessary for a deeper integration of your system with ours. You can also use secuOffice to manage the further order processing. See Order Processing for more details.

Step 1: Authenticate with OAuth 2.0

The endpoint for OAuth authentication is POST /oauth/token.

Request
POST /oauth/token HTTP/1.1
Host: connect-testing.secuconnect.com
Content-Type: application/json
Accept: application/json
 
{
"grant_type": "client_credentials",
"client_id": "00563697073442633035025909838580",
"client_secret": "3382456441636938321687549172178382320163695870914358804052148567"
}

If everything is fine, it responds with 200 OK and the token details:

Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
"access_token": "qb56tjj1bcvo9n2nj4u38k84lo",
"expires_in": 1200,
"token_type": "bearer",
"scope": "https://scope.secucard.com/e/api"
}

You need to pass the received token with your subsequent calls, using the Authorization: Bearer HTTP header. The above token is qb56tjj1bcvo9n2nj4u38k84lo, and it is valid for the next 1,200 seconds.

Step 2: 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.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"is_demo": true,
"contract": {
"id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
},
"provider_contract": {
"id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8"
},
"customer": {
"contact": {
"forename": "Max",
"surname": "Mustermann",
"phone": "+49 555 5555555",
"mobile": "+49 177 5555555",
"address": {
"street": "Musterstr.",
"street_number": "55 a",
"additional_address_data": "Whg. 203",
"postal_code": "09123",
"city": "Musterstadt",
"country": "DE"
},
"email": "max@example.net",
"dob": "1980-01-01"
}
},
"intent": "order",
"basket": {
"products": [
{
"item_type": "sub_transaction",
"desc": "Warenkorb Musterhändler Kaffee & Tee",
"sum": 3940,
"reference_id": "sb0",
"contract_id": "GCR_FN6CUOWY6VJKDHY0VIPHFM9344NKX7",
"sub_basket": [
{
"id": 1,
"articleNumber": 1,
"desc": "Kaffeepads Aromata 20 Stück",
"quantity": 2,
"priceOne": 1995,
"tax": 19
},
{
"id": 1000,
"item_type": "shipping",
"name": "Standardversand",
"quantity": 1,
"priceOne": 450,
"tax": 19
},
{
"item_type": "stakeholder_payment",
"desc": "Marktplatzgebühr",
"sum": 80,
"reference_id": "fee",
"contract_id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
}
]
},
{
"item_type": "sub_transaction",
"desc": "Warenkorb Musterhändler Einrichtung",
"sum": 3345,
"reference_id": "sb1",
"contract_id": "GCR_G8GOXJU27Z4JO9XONAH8ANLSF9OO30",
"sub_basket": [
{
"id": 1,
"articleNumber": 1,
"desc": "Magnettafel 70x50 cm",
"quantity": 1,
"priceOne": 2995,
"tax": 19
},
{
"id": 1000,
"item_type": "shipping",
"name": "Standardversand",
"quantity": 1,
"priceOne": 350,
"tax": 19
},
{
"item_type": "stakeholder_payment",
"desc": "Marktplatzgebühr",
"sum": 70,
"reference_id": "fee",
"contract_id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
}
]
}
]
},
"basket_info": {
"sum": 7285,
"currency": "EUR"
},
"delivery_options": {
"type": "shipping"
},
"application_context": {
"checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
"language": "de",
"return_urls": {
"url_success": "https://shop.example.com/SUCCEESS",
"url_error": "https://shop.example.com/FAILURE",
"url_abort": "https://shop.example.com/DENIAL"
}
},
  "payment_context": {
"auto_capture": true
}
}

This creates a demo transaction with sub-baskets for two of your suppliers. The marketplace earns a fee of €1.50.

If everything is fine, the API responds with 200 OK and a representation of the newly created Smart Transaction:

Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
"object": "smart.transactions",
"id": "STX_3823Y85JF2P6BZS5C7TH6DTSGKUEA2",
"merchant": {
"object": "general.merchants",
"id": "MRC_SP02GWXS3FVVX0MFN2F95BN9F8SCE2",
"companyname": "Mustermarktplatz GmbH"
},
"provider_contract": {
"object": "general.contracts",
"id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8"
},
"contract": {
"object": "general.contracts",
"id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
},
"customer": {
"object": "payment.customers",
"id": "PCU_WAD6FUDZH2P6BGR48A2UV78BGRDAAJ",
"contact": {
"name": "Max Mustermann",
"forename": "Max",
"surname": "Mustermann",
"dob": "1980-01-01T00:00:00+00:00",
"email": "max@example.net",
"phone": "+495555555555",
"mobile": "+491775555555",
"address": {
"street": "Musterstr.",
"street_number": "55a",
"additional_address_data": "Whg. 203",
"postal_code": "09123",
"city": "Musterstadt",
"country": "DE"
}
}
},
"transactions": [],
"created": "2023-08-03T14:01:14+02:00",
"status": "created",
"intent": "order",
"basket": {
"products": [
{
"item_type": "sub_transaction",
"desc": "Warenkorb Musterhändler Kaffee & Tee",
"reference_id": "sb0",
"contract_id": "GCR_FN6CUOWY6VJKDHY0VIPHFM9344NKX7",
"sum": 3940,
"sub_basket": [
{
"id": 1,
"item_type": "article",
"desc": "Kaffeepads Aromata 50 Stück",
"articleNumber": "1",
"quantity": 2,
"priceOne": 1995,
"tax": 19
},
{
"id": 1000,
"item_type": "shipping",
"desc": "Standardversand",
"quantity": 1,
"priceOne": 450,
"tax": 19
},
{
"item_type": "stakeholder_payment",
"desc": "Marktplatzgebühr",
"reference_id": "fee",
"contract_id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2",
"sum": 80
}
]
},
{
"item_type": "sub_transaction",
"desc": "Warenkorb Musterhändler Einrichtung",
"sum": 3345,
"reference_id": "sb1",
"contract_id": "GCR_G8GOXJU27Z4JO9XONAH8ANLSF9OO30",
"sub_basket": [
{
"id": 1,
"articleNumber": 1,
"desc": "Magnettafel 70x50 cm",
"quantity": 1,
"priceOne": 2995,
"tax": 19
},
{
"id": 1000,
"item_type": "shipping",
"name": "Standardversand",
"quantity": 1,
"priceOne": 350,
"tax": 19
},
{
"item_type": "stakeholder_payment",
"desc": "Marktplatzgebühr",
"sum": 70,
"reference_id": "fee",
"contract_id": "GCR_2MNKTWOFO6FPYI2DW7AM1LK21P1HJ2"
}
]
}
],
"type": "mixed"
},
"basket_info": {
"sum": 7285,
"currency": "EUR"
},
"is_demo": true,
"delivery_options": {
"type": "shipping"
},
"application_context": {
"checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
"language": "de",
        "return_urls": {
"url_success": "https://shop.example.com/PAYMENT-SUCCEEDED",
"url_error": "https://shop.example.com/PAYMENT-FAILED",
"url_abort": "https://shop.example.com/PAYMENT-ABORTED"
},
},
  "payment_context": {
"auto_capture": true
},
"checkout_links": {
"url_checkout": "https://checkout-dev.secuconnect.com?wizardFlow=checkout&stx=STX_3823Y85JF2P6BZS5C7TH6DTSGKUEA2&viewMode=fullscreen&basketDisplay=full&server=dev6"
}
}

Important fields are:

Field

Type

Meaning

id

string

The object ID of the new Smart Transaction.

status

string

The status of the Smart Transaction, currently created.

payment_links

string[]

The payment links to start the Smart Checkout. (See details below.)

Most interesting is the ID of the Smart Transaction. Your application may need it for subsequent calls.

For further explanation of the fields, see our API Reference: link

Step 3: Start Smart Checkout

The URL in  payment_links/general  opens Smart Checkout with the payment method selection. The other links only offer the necessary steps for the respective payment method.

For demonstration, we simply put the URL into our browser's address bar to opens Smart Checkout full-screen:

In some cases the user might be directed back to the success, failure, or abort URL immediately.

Please consider that some flows will escape Iframes. These can be forbidden (klarna Sofort), or the strict security measures of modern browsers will break the process. We recommend to open Smart Checkout in full screen.

Step 4: Receive the Buyer at the Return URLs

You can pass return URLs for the case of success or failure. These URLs will be opened by the browser in most cases of success and many cases of failure.

In the case of failure you would like to repeat the payment process.

In the case of success you would read the Smart Transaction in order to obtain the current status, and the ID of the Payment Transaction (PCI_xyz). The Payment Transaction ID is used in the further process and should be saved with the order.

The API endpoint to read a Smart Transaction is GET /api/v2/Smart/Transactions/{id} :

Request
GET /api/v2/Smart/Transactions/STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

A request body is not needed.

If everything is fine, the API responds with 200 OK and a representation of the Smart Transaction:

Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"object": "smart.transactions",
"id": "STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ",
// ...
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_MVFGGPZR5CADLVRAJVB05QBN3CO90O",
"trans_id": 110099700,
"transaction_hash": "ebbtpsnzmrnd11060206"
}
],
  "created": "2020-02-04T15:34:00+01:00",
"updated": "2020-02-04T15:34:56+01:00",
  "status": "pending",
// ...
  "payment_method": "prepaid",
"payment_instructions": {
"owner": "secupay AG",
"iban": "DE81850400611005523759",
"bic": "COBADEFFXXX",
"bankname": "Commerzbank CC",
"purpose": "TA 110099700",
"girocode_url": "https://connect-testing.secupay-ag.de/qr/epc?stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ"
},
"trans_id": 110099700,
// ...
}

The most important changes are:




transactions

array

Transactions connected to the Smart Transactions. Marketplaces have mixed basket transactions with one Payment Transaction for the entire order. Additional sub-transactions for the sub-baskets will appear. See Mixed Baskets Transactions for Marketplaces for details.

status

string

The status of the Smart Transaction. In this situation it should be one of:

  • approved
  • pending
  • ok

payment_method

string

The payment method used here. It should be one of:

  • creditcard
  • debit
  • eps
  • easycredit
  • giropay
  • invoice
  • paypal
  • prepaid
  • sofort

payment_instructions

object

Only present for payment method  invoice  or  prepaid. These must be communicated to the payer to make the payment.

trans_id

string

The ID of the leading Payment Transaction (“original transaction”) in the old format.

Your application will need the Payment Transaction IDs for the further order processing.

See Also