Integrate Smart 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/005e85f39190a0451f449f8f0ea43869719efadbb1027a3e5a12d9ca2ac7870b.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"
}

Successful response:

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 (line 6) in an Authorization: Bearer header in your subsequent calls. The returned OAuth token (line 6) is valid for as many seconds as signalized in the expires_in field (line 8).

Step 2: Create the Smart Transaction

The following example is for regular webshops. The differences are described for the creation of the Smart Transaction. (See link below.)

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": "coupon",
"desc": "Coupon €5.00",
"quantity": 1,
"priceOne": 500,
"tax": 19
}
       ]
},
"basket_info": {
"sum": 4485
},
"application_context": {
"checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
       "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 Smart Transaction with a total amount of €49.85. The gross unit prices of the above articles are €15.95, and €17.95.

The request details are described in detail with the creation of the Smart Transaction (see link below). Important for the Smart Checkout are the application_context object, and the payment_context object:

Details of the application_context object (incomplete):

Field

Type

Meaning

return_urls

object

Optional return URLs for Smart Checkout to redirect the buyer to after the successful or failed checkout process.

checkout_template

string

Checkout template. I controls the page flow and fields of Smart Checkout:

  • COT_WD0DE66HN2XWJHW8JM88003YG0NEA2 for regular payment (incl. easyCredit)

  • COT_QV85D3F542XWFFJYCSWG00W400YWAT for subscriptions

  • COT_3DP70FK5H2XP02TCVQ28000NG095A2 for easyCredit

language

string

Optional display language for Smart Checkout:

  • de for German;

  • en for English.

Details of the return_urls object (inside application_context):

Field

Type

Meaning

url_success

string

Optional URL the buyer is redirected to after successful Smart Checkout.

url_error

string

Optional URL the buyer is redirected to when the checkout failed.

url_abort

string

Optional URL the buyer is redirected to when he stopped the checkout process intentionally.

url_failure

string

Optional URL the buyer is redirected to after failed Smart Checkout. This is write-only, and sets url_error and url_abort.

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.

  • true shows the "Buy now!" button, and captures the payment;

  • false shows the "Continue!" button, and only authorises the payment.

Defaults to false, needs explicit capture.

If everything is fine, the API responds with 200 OK and the representation of the 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": 0,
"parent": null,
"articleNumber": null,
"ean": null,
"desc": "ACME ball pen Modern Line 8050",
"quantity": 2,
"priceOne": 1595,
"tax": 19,
"group": null,
"serialNumber": null,
"item_type": "article",
"reference_id": null
},
{
"id": 1,
"parent": null,
"articleNumber": null,
"ean": null,
"desc": "ACME pen case Modern Line",
"quantity": 1,
"priceOne": 1795,
"tax": 19,
"group": null,
"serialNumber": null,
"item_type": "article",
"reference_id": null
}
],
...
},
"basket_info": {
"sum": 4985,
"currency": "EUR",
...
},
"is_demo": true,
...
"application_context": {
"checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
        "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,
"payment_methods": null,
"merchant_initiated": false,
"accrual": false,
"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"
}
}

As you see, the system behind the secuconnect API added many things. The most interesting are:

Field

Type

Meaning

id

string

The ID of the new Smart Transaction object. You need it for the subsequent API calls.

status

string

The status of the Smart Transaction, currently created.

payment_links

string[]

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

Details of the payment_links object:

Field

Type

Meaning

creditcard

string

URL to start Smart Checkout to pay with credit card.

debit

string

URL to start Smart Checkout to pay with SEPA direct debit.

eps

string

URL to start Smart Checkout to pay with EPS (for Austria).

easycredit

string

URL to start Smart Checkout to pay with easyCredit Ratenkauf (instalment payment).

giropay

string

URL to start Smart Checkout to pay with giropay (for Germany).

invoice

string

URL to start Smart Checkout to pay on account with bank transfer.

paypal

string

URL to start Smart Checkout to pay with PayPal.

prepaid

string

URL to start Smart Checkout to pay in advance with bank transfer.

sofort

string

URL to start Smart Checkout to pay with klarna Sofort.

general

string

URL to start Smart Checkout for payment with any contracted and matching method.

Most interesting is the ID of the Smart Transaction so far, and one of the URLs.

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. This may include steps like entering credit card data, or bank details, and an external authorisation flow. In some cases the user might be directed back to the success, failure, or abort URL immediately.

For demonstration, we simply put the URL into our browser's address bar. This opens Smart Checkout fullscreen:

images/download/attachments/141539269/image2023-1-24_13-49-59.png

As you can see, it is very easy.

Please consider that some flows will escape iframes, since these can be forbidden (klarna Sofort), or the strict security measures of modern browsers make would break the process. Thus we recommend to open Smart Checkout always in fullscreen.

Step 4: Receive the Buyer at the Return URLs

As explained with the creation of the Smart Transaction, 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 repeat the payment process. This might include to set an order object to an appropriate status.

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 needed to process the status updates, and should be saved along the order. You would also set your order object to an appropriate status, and confirm 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.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 the 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,
...
}