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):
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):
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.
POST /oauth/token HTTP/1.1Host: connect-testing.secupay-ag.deContent-Type: application/jsonAccept: application/json{ "grant_type": "client_credentials", "client_id": "09ae83af7c37121b2de929b211bad944", "client_secret": "9c5f250b69f6436cb38fd780349bc00810d8d5051d3dcf821e428f65a32724bd"}Successful response:
HTTP/1.1 200 OKContent-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:
POST /api/v2/Smart/Transactions HTTP/1.1Host: connect-testing.secupay-ag.deAuthorization: Bearer qb56tjj1bcvo9n2nj4u38k84loContent-Type: application/jsonAccept: 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:
HTTP/1.1 200 OKContent-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:
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.