Integrate Smart Checkout for Webshops

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

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:

images/inline/423aceace49ffc001085334d46b128caf8e0b1d7e983137cff165b7fbbd39c73.png

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 required

  • 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 authorization is POST / oauth/token.

Request
POST /oauth/token HTTP/1.1
Host: connect-testing.secupay-ag.de
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.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"is_demo": true,
"contract": {
"id": "GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04"
},
"customer": {
"contact": {
"forename": "Max",
"surname": "Mustermann",
"phone": "+49 555 5555555",
"mobile": "+49 177 5555555",
"address": {
"street": "Musterstr.",
"street_number": "11",
"additional_address_data": "App. 302",
"postal_code": "09123",
"city": "Musterstadt",
"country": "DE"
},
"email": "max@example.org",
"dob": "1965-12-31"
}
},
"intent": "sale",
"basket": {
"products": [
{
"id": 1,
"desc": "ACME ball pen Modern Line 8050",
"priceOne": 1595,
"tax": 19,
"quantity": 2
},
{
"id": 2,
"desc": "ACME pen case Modern Line",
"priceOne": 1795,
"tax": 19,
"quantity": 1
},
{
        "id": 3,
"item_type": "shipping",
"desc": "Standardversand",
"priceOne": 495,
"tax": 19
      }
   ]
},
"basket_info": {
"currency": "EUR",
"sum": 5480
},
"application_context": {
"checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
"language": "de",
    "return_urls": {
"url_success": "https://shop.example.com/payment/success",
"url_error": "https://shop.example.com/payment/failure",
"url_abort": "https://shop.example.com/payment/denial"
}
},
"payment_context": {
"auto_capture": true
}
}

This creates a Smart Transaction with two articles and a shipping fee, having a total amount of €49.85.

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_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ",
"merchant": {
"object": "general.merchants",
"id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8",
"companyname": "Smart Checkout Testmerchant 8"
},
"contract": {
"object": "general.contracts",
"id": "GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04"
},
"created": "2020-02-04T15:34:00+01:00",
"status": "created",
"basket": {
"products": [
{
"id": 1,
"desc": "ACME ball pen Modern Line 8050",
"quantity": 2,
"priceOne": 1595,
"tax": 19,
"item_type": "article"
},
{
"id": 2,
"desc": "ACME pen case Modern Line",
"quantity": 1,
"priceOne": 1795,
"tax": 19,
"item_type": "article"
},
{
"id": 2,
"item_type": "shipping",
"desc": "Standardversand",
"quantity": 1,
"priceOne": 495,
"tax": 19
}
],
},
"basket_info": {
"sum": 5480,
"currency": "EUR",
},
"is_demo": true,
"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,
"creditcard_schemes": [
"mastercard",
"visa",
"american express"
]
},
"payment_links": {
"creditcard": "https://pay.secupay.com?payment-method=creditcard&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
"debit": "https://pay.secupay.com?payment-method=debit&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
"easycredit": "https://pay.secupay.com?payment-method=eps&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
"eps": "https://pay.secupay.com?payment-method=eps&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
"giropay": "https://pay.secupay.com?payment-method=giropay&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
  "invoice": "https://pay.secupay.com?initPaymentMethod=invoice&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
"paypal": "https://pay.secupay.com?payment-method=paypal&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
  "prepaid": "https://pay.secupay.com?payment-method=prepay&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
"sofort": "https://pay.secupay.com?payment-method=sofort&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
"general": "https://pay.secupay.com?stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing"
}
}

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.

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:

images/download/attachments/194939204/Smart_Checkout_1000x650_f0f0f0-version-1-modificationdate-1698854108000-api-v2.jpg

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 the Smart Transaction is GET /api/v2/Smart/Transactions/{id}:

Request
GET /api/v2/Smart/Transactions/STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ HTTP/1.1
Host: connect-testing.secupay-ag.de
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:

Field

Type

Meaning

transactions

array

Transactions connected to the Smart Transactions. Normal web shops have one Payment Transaction.

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 Payment Transaction in the old format. Helpful for service requests.

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