Smart 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

This is the process if the final confirmation can be handled by Smart Checkout (with auto_capture):

images/inline/1f45ca3f7b33d45556c0564e894747745ce362fe6a997534fc4735064c7523e9.png

The customer details can 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

Everything in this process is managed by our Smart Checkout, and you don't need to card for the details. The customer will only be prompted for the required decisions and details.

This is the process if the final confirmation must be handled back at the merchant's website (with explicit capture):

images/inline/6c2e39751e6bcbbd0cd48af42232a666df47ca9a4fe052d445e81a6c30c11c5e.png

The only difference is in the final confirmation on your website. It requires another API call to start the Smart Transaction and capture the payment.

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": "09ae83af7c37121b2de929b211bad944",
"client_secret": "9c5f250b69f6436cb38fd780349bc00810d8d5051d3dcf821e428f65a32724bd"
}

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 API endpoint to create a Smart Transaction is POST https://connect.secucard.com/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_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
"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": false
}
}

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.

Monetary amounts are expressed in the smallest currency unit (e. g. Euro Cent).

The Checkout Template ID in application_context/checkout_template controls the exact fields and page flow of Smart Checkout:

  • COT_WD0DE66HN2XWJHW8JM88003YG0NEA2 for regular payment (incl. easyCredit)

  • COT_QV85D3F542XWFFJYCSWG00W400YWAT for subscriptions

  • COT_3DP70FK5H2XP02TCVQ28000NG095A2 for easyCredit

  • default null: deprecated

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_AZS7P6FTNTC6NK0QWFDBREW94ZY2O7",
"companyname": "Smart Checkout Testmerchant 8"
},
...
"contract": {
"object": "general.contracts",
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
...
"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": false,
"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_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
"debit": "https://pay.secupay.com?payment-method=debit&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
"easycredit": "https://pay.secupay.com?payment-method=eps&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
"eps": "https://pay.secupay.com?payment-method=eps&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
"giropay": "https://pay.secupay.com?payment-method=giropay&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
    "invoice": "https://pay.secupay.com?initPaymentMethod=invoice&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
"paypal": "https://pay.secupay.com?payment-method=paypal&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
    "prepaid": "https://pay.secupay.com?payment-method=prepay&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
"sofort": "https://pay.secupay.com?payment-method=sofort&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing",
"general": "https://pay.secupay.com?stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_2H69XY35227V2VKP9WRA3SJ0W95RP0&server=testing"
}
}

As you see, the secuconnect API service added a lot of things. Most interesting for you are the ID of the Smart Transaction (line 8), and the payment links.

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/image2020-2-4_16-13-44.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.

See Also