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
.
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:
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
.
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:
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 |
---|---|---|
|
| The object ID of the new Smart Transaction. |
|
| The status of the Smart Transaction, currently |
|
| 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}
:
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:
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 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. |
|
| The status of the Smart Transaction. In this situation it should be one of:
|
|
| The payment method used here. It should be one of:
|
|
| Only present for payment method |
|
| 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.