Integration Guide for Payment (secuconnect API + Smart Checkout)

Introduction

This guide shows how you can use the secuconnect API to integrate our Smart Checkout. This is very flexible, and you can customize the Smart Checkout in many ways. If you want to have more control or cover exceptional use cases, you can also use the Smart Transaction directly to implement a custom checkout process. There are also ready-to-use shop modules for many popular shop systems. Please do not hesitate to ask our sales team or help desk for their assistance. You are very welcome!

The integration guide begins with a Getting Started section, that explains the basic concepts and important key terms. In this section, you will learn how to create a first order and start the Payment Wizard. We recommend to study the Getting Started section thoroughly. The remaining sections, Reference and Troubleshooting can be accessed when needed. Should you require assistance with integration or further order processing, our support staff will be happy to help.

Getting Started

Key Terms

Merchant and Contract

The merchant sells products to the customer or offers a service. Thus he delivers something and receives the payment for it. As payment service provider (PSP), secupay cares for the payment and interacts with both, the merchant and his customer.

Every merchant can have one or more contracts with secupay for different purposes. These contracts are managed behind the scenes for you. Important for you: Yuo will receive one or more contract IDs (GCR_xxx), and some information for which purpose you shall use them.

Smart Transaction and Payment Transaction

A Payment Transaction manages the payment process between secupay and your customer as well as between secupay and you, the merchant. It is defined by the payer and the payee, the payment method and the amount.

A Smart Transaction is rather a business transaction like a purchase order. It knows about the status of the payment, and manages delivery and the like. The Payment Transaction is managed by the Smart Transaction, and associated to it.

Payment Workflows

There are two basic payment workflows:

  • sale: The customer makes the final payment confirmation in the secupay Smart Checkout.

  • authorization: The customer only authorizes the payment in the Smart Checkout. After this, the merchant needs to call the secuconnect API again to in order for secupay to execute the payment.

These two processes are referred to as intents in relation to the Smart Transaction.

The sale workflow:

  1. The merchant's application cares to create a new Payment Customer or to create a new one, using the secuconnect API.

  2. The merchant's application prepares a Smart Transaction with the intent sale using the secuconnect API.

  3. The customer finishes the checkout using the Smart Checkout by secupay.

  4. The Smart Checkout directs the customer to a success URL of the merchant.

When all steps of the process are completed successfully, the Smart Transaction and the linked Payment Transaction are waiting for a pending payment, or are finally approved. It is not guaranteed that the customer opens the offered success URL.

If the customer aborts the payment, he is directed to a failure URL. It is also not guaranteed that the customer opens this URL. They can also simply stop to interact with the browser or close the browser window.

The authorization workflow:

  1. The merchant's application cares to create a new Payment Customer or to create a new one, using the secuconnect API.

  2. The merchant's web application prepares a Smart Transaction with intent authorization using the secuconnect API.

  3. The customer authorizes the payment using the Smart Checkout by secupay.

  4. The Smart Checkout directs the customer to a success URL of the merchant.

  5. The customer finishes the checkout in the merchant's web application.

  6. The merchant's application calls the secuconnect API in order to start the Smart Transaction, executing the payment.

Completing these steps leaves a Smart Trasaction with a Payment Transaction waiting for the payment or finally approved. If the authorization fails, the failure URL is called, allowing to repeat the process. In both cases there is no guarantee the customer opens one of these URLs.

The return URLs are not always necessary. The intent sale can be operated without a success URL. See more in the Reference section.

Working Example

In our example we will:

  1. Authenticate against the secuconnect API

  2. Create a Payment Customer

  3. Create a Smart Transaction

  4. Start the Smart Checkout

The transaction will use the sale workflow and the demo mode. In this mode the payment is not really executed.

Step 1: Authenticate Against secuconnect API

Most API calls require authentication. The secuconnect API uses the OAuth 2.0 protocol for authentication. The OAuth service checks your credentials, and hands an access token over to you. It grants you access to the API for a limited period of time. The client must pass this token with all subsequent API calls.

The endpoint for OAuth authorization is POST https://connect.secucard.com/ oauth/token.

Example request:

POST /oauth/token HTTP/1.1
Host: connect.secucard.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 151
 
grand_type=client_credentials&client_id=129b362607f87990bdf5589a0be3a04d&client_secret=31e991b25b7896a3fad567507f7eb38feaef9329657a4a8cd30fbe6eecf5f50b

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
...
 
{
"access_token": "qb56tjj1bcvo9n2nj4u38k84lo",
"expires_in": 1200,
"token_type": "bearer",
"scope": "https://scope.secucard.com/e/api"
}

The returned access token is valid for as many seconds as signalised in the expires_in field (line 8). You need to pass the received token (line 7) in an HTTP request header Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo of the subsequent calls.

Usually, direct usage of HTTPS is not necessary, but for can be useful for debugging and to understand the SDK.

The corresponding example using the secuconnect PHP SDK:

use \Secuconnect\Client\Configuration;
use \Secuconnect\Client\Authenticator;
use \Secuconnect\Client\OauthCredentials;
 
// Optionally you can configure a PSR-6 compliant cache
Configuration::getDefaultConfiguration()->setCache($cache);
 
// Create an authenticator object with OAuth authentication and obtains token
$auth = new Authenticator(OauthClientCredentials::from($clientId, $clientSecret));
$accessToken = $auth->getToken();
 
// Saves the token to the default client configuration
Configuration::getDefaultConfiguration()->setAccessToken($accessToken);

We provide SDKs for PHP, Java, NodeJS, and .NET free of charge.

Step 2: Create A Payment Customer

The API endpoint to create a Smart Transaction is POST https://connect.secucard.com/api/v2/Payment/Customers.

Example request:

POST /api/v2/Payment/Customers HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
...
 
{
"contact": {
"salutation": "Mr.",
"forename": "Max",
"surname": "Mustermann",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE",
"additional_address_data": "Whg. 202"
},
"email": "mmustermann@example.net",
"mobile": "+49 177 5555555",
"phone": "+49 555 5555555"
}
}

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "payment.customers",
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ",
"merchant": {
"object": "general.merchants",
"id": "MRC_DNUWH3RE6J6TNRGW0X607S294W0XO3"
},
"contact": {
"salutation": "Mr.",
"forename": "Max",
"surname": "Mustermann",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE",
"additional_address_data": "Whg. 202"
},
"email": "mmustermann@example.net",
"mobile": "+49 177 5555555",
"phone": "+49 555 5555555"
}
}

The most important field is id. It identifies this single customer, and you need it to create the Smart Transaction.

Step 3: Create A Smart Transaction

The API endpoint to create a Smart Transaction is POST https://connect.secucard.com/api/v2/Smart/Transactions.

Example request:

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
...
 
{
"intent": "sale",
"is_demo": true,
"contract": {
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
"customer": {
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ"
},
"transactionRef": "Hotelbuchung 23.10.2020 für Hrn. Muster, Musterfirma GmbH Musterstadt",
"basket_info": {
"sum": 11970
},
"application_context": {
"return_urls": {
"url_success": "https://www.example.org/SUCCESS",
"url_failure": "https://www.example.org/FAILURE"
},
"iframe_opts": {
"language": "de_DE"
}
}
}

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"merchant": {
"object": "general.merchants",
"id": "MRC_AZS7P6FTNTC6NK0QWFDBREW94ZY2O7",
"companyname": "Smart Checkout Testmerchant 8"
},
"provider_contract": {
"object": "general.contracts",
"id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8"
},
"contract": {
"object": "general.contracts",
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
"customer": {
"object": "payment.customers",
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ",
"contact": {
"forename": "Max",
"surname": "Mustermann",
"name": "Max Mustermann",
"salutation": "Mr.",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"additional_address_data": "Whg. 202",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE"
},
"email": "mmustermann@example.net",
"mobile": "+491775555555",
"phone": "+495555555555"
}
},
"transactions": [],
"created": "2020-03-27T10:55:23+01:00",
"status": "created",
"transactionRef": "Hotelbuchung 23.10.2020 für Hr. Muster, Musterfirma GmbH Musterstadt",
"intent": "sale",
"basket_info": {
"sum": 11970,
"gratuity": null,
"currency": "EUR"
},
"is_demo": true,
"application_context": {
"locks": {
"customer": true
},
"return_urls": {
"url_success": "https://www.example.org/SUCCESS",
"url_error": "https://www.example.org/FAILURE",
"url_abort": "https://www.example.org/FAILURE"
},
"iframe_opts": {
"payment_hint_title": null,
"payment_hint": null,
"project_title": null,
"submit_button_title": null,
"cancel_button_title": null,
"language": "en_US",
"basket_title": null,
"hide_disclaimer": null,
"has_accepted_disclaimer": null
}
},
"checkout_links": null,
"payment_links": {
"creditcard": "https://checkout.secupay.com?initPaymentMethod=Creditcard&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"debit": "https://checkout.secupay.com?initPaymentMethod=Debit&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"invoice": "https://checkout.secupay.com?initPaymentMethod=Invoice&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"prepaid": "https://checkout.secupay.com?initPaymentMethod=Prepay&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"general": "https://checkout.secupay.com?stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2"
}
}

As you see, the system behind the secuconnect API added many things. Most interesting for you are

  • the ID of the Smart Transaction, here STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2;

  • and the payment URLs (payment_links/*).

You need the Smart Transaction ID to capture or cancel the payment. The next section explains how to use the payment URLs.

Step 4: Open The Smart Checkout

The payment URLs in the STX are to be used to start the Smart Checkout. After the customer completed the wizard, he is directed to one of the return_urls, we have passed in the application_context before.

There are these payment URLs in the above STX:

  • payment_links/creditcard: One can only pay by credit card.

  • payment_links/debit: One can only pay by direct debit.

  • payment_links/invoice: One is only offered invoice payment.

  • payment_links/prepaid: One is only offered advance payment.

  • payment_links/general: One is only offered every payment method, that is eligible. If the first attempt fails, he is offered another method or prompted for another payment instrument as long as this makes sense.

We simply open one of the URLs from payment_links in our browser. Here the variant for credit card payment:

images/download/attachments/95096238/image2020-3-27_16-18-0.png

And here the variant with payment method selection.

images/download/attachments/95096238/image2020-3-27_16-18-49.png

Summary

You have seen how to integrate our Smart Checkout with your application using our secuconnect API. We have created a Payment Customer and a Smart Transaction, and started the Smart Checkout in a browser.

Furthermore you can:

  • Let our secuconnect SDKs assemble requests, and parsing responses

  • Display a project summary, and logo

  • Display a detailed basket, or cost summary

  • Pass and display a mixed basket for multiple merchants (for marketplaces)

  • Pass stakeholder shares, for instance to pay out sales provisions

  • Define static or individual URLs to direct the customer back to your page after successful or failed checkout

  • Change the default language of the Checkout Wizard

  • Change the text of the confirmation button

  • Change the primary design colour or set a background image instead of the grey frame.

Some of the mentioned things are described in the Reference section below. If you don't find the needed information, please do not hesitate to ask us.

Reference

Demo or Production

You can create your particular Smart Transaction in demo mode. This is useful for testing, especially during integration.

{
"is_demo": true,
...
}

For demo transactions, no payment is being processed. Demo transactions can be filtered and excluded in SecuOffice.

The demo mode is a boolean value:

  • true: The Smart Transaction is marked as demo transaction. The payment is not processed.

  • false: The Smart Transaction is handled as a productive one. The payment will be processed.

The default value is false, a productive transaction.

There can be different payment methods configured for demo and production. If a particular payment method is available in production mode, it must not necessarily be in demo mode, and vice versa.

Do not forget to change the parameter when you make tests including our live system. Also do not forget to switch to prduction, when you go live. The resulting transaction cannot be changed anymore, but only be cancelled.

Instant Execution or Authorization

Using intent, you can decide about the flow:

  • sale: The Smart Checkout ends with final closure of the contract. The payment is executed immediately.

  • authorization: The Smart Checkout ends with an 'Continue' button. The execution of the payment needs an additional API call to start the Smart Transaction, and execute the payment.

You have seen the example for sale in the Getting Started section.

Here is an example for the authorization flow. When you create the STX, you simply pass another intent:

{
"intent": "authorization",
...
}

When the customer was returned to your success URL, you ask him for final confirmation. Then you call POST /api/v2/Smart/Transactions/<STX_xxx>/start:

POST /api/v2/Smart/Transactions/STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ/start HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
...
 
{
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ",
...
"status": "pending",
...
}

If everything is fine, the secuconnect API responds the request with 200 OK. The Smart Transaction returned has either status pending or ok.

Passing a Order ID and Purpose

There are two fields to pass your order ID and the purpose to the transaction. The order ID helps you to connect with your system. The purpose is shown at the bank statements of the customer, but also in your advice notes for the payout.

The field names are:

  • merchantRef: your order ID;

  • transactionRef: purpose text.

Example request body:

{
...
"merchantRef": "500015241",
"transactionRef": "Müller Sep/25/2020-Sep/29/2020",
...
}

Basket Details

The basket items are passed in the object node basket/products. They need to have these mandatory details:

  • item ID;

  • quantity;

  • article name;

  • gross unit price;

  • VAT rate.

Additionally, you can also pass:

  • your article number, or storage keeping unit (SKU);

  • the official EAN (or GTIN) of this product.

Full example:

{
...
"basket": {
"products": [
{
"id": 0,
"articleNumber": "ACM/BPMOD-8050",
"ean": "4123456789012",
"desc": "ACME ball pen Modern Line 8050",
"quantity": 2,
"priceOne": 1595,
"tax": 19
},
{
"id": 1,
"articleNumber": "ACM/CASMOD",
"ean": "4123500055537",
"desc": "ACME pen case Modern Line",
"quantity": 1,
"priceOne": 1795,
"tax": 19
}
],
...
},
"basket_info": {
"sum": 4985,
"currency": "EUR",
...
},
...
}

Detailed description of the objects for the basket items:

Attribute

Type

Description

id

number

The item ID as integer. It is necessary as handle for further changes.

quantity

number

The amount as integer.

articleNumber

string

Optional. Your internal article number, or storage keeping unit (SKU).

ean

string

Optional. The official EAN or GTIN of this product.

Note: If your product has no EAN or GTIN, please omit this attribute. It might conflict with real GTINs that need to be evaluated by use. We need to evaluate EANs when you start a loyalty card programme to detect loyalty cards, or articles with special tax handling. We also need to evaluate EANs when you start to sell e-goods, phone charge for example.

name

string

The article name.

price

number

The gross unit price in the minor currency unit.

If you pass a value of 1595 for a order in Euros, this means 1595 Euro Cents, or €15,95.

tax

number

The value-added tax (VAT) rate in percent.

If you pass a value of 19, this means a VAT rate of 19%.

You can also change the basket title in the contract settings or in the Smart Transaction.

Here the visual outcome:

images/download/attachments/95096238/image2020-3-27_16-59-33.png

More Display Options

There are a number of options to control the appearance of the Smart Checkout. In general, there are two ways to set these options. You ask our help desk to set options for your contract, or you can pass the options during the creation of a Smart Transaction. Per-contract options affect both the Smart Checkout and the Checkout Wizard. Options passed to the Smart Transaction are only effective for this particular transaction.

First an overview about the options:

Option

Contract Setting

Transaction Attribute

show basket (instead of total sum)

yes

headline above basket

yes

basket_title

project name

yes

project_title

project logo

yes

payment hint (2-column info table)

payment_hint

headline above payment hint

yes

payment_hint_title

language

yes

language

formal or informal speech

yes

submit button label

yes

submit_button_title

cancel button label

cancel_button_title

primary design color (HTML color)

yes

hide disclaimer

hide_disclaimer

has accepted disclaimer

has_accepted_disclaimer

Example of a Smart Transaction:

{
...
"merchantRef": "500015241",
"transactionRef": "Müller Sep/25/2020-Sep/29/2020",
"application_context": {
"iframe_opts": {
"payment_hint_title": "Infos zu deiner Reservierung",
"payment_hint": [
{
"type": "name-value",
"value": {
"name": "Reisedatum:",
"value": "25.09.2020 - 29.09.2020"
}
},
{
"type": "name-value",
"value": {
"name": "Personen:",
"value": "2 Erwachsene, 2 Kinder"
}
},
{
"type": "name-value",
"value": {
"name": "Zimmer:",
"value": "Appartment gehoben"
}
},
{
"type": "name-value",
"value": {
"name": "Reservierungsnummer:",
"value": "500015241"
}
},
{
"type": "name-value",
"value": {
"name": "Gesamtpreis:",
"value": "228,00 EUR"
}
},
{
"type": "name-value",
"value": {
"name": "Anzahlung 20 %:",
"value": "45,60 EUR"
}
}
],
"submit_button_title": "Kostenpflichtig buchen!",
"cancel_button_title": "Zurück zur Reiseansicht",
"language": "de_DE",
"hide_disclaimer": true,
"has_accepted_disclaimer": true
}
},
...
}

Here the visual outcome:

images/download/thumbnails/95096238/image2020-3-27_17-2-47.png

Explanation of the application context attributes:

Attribute

Type

Description

1

basket_title

string

Replace the headline of the basket with a custom one. Only effective in the Smart Checkout and only when the basket is shown instead of the order total (contract option).

2

project_title

string

Display project name above the order total or the basket. Intented for crowd funding projects, etc. Only effective in the Smart Checkout.

3

payment_hint

array

Two-column info table. It can be used to explain the partition of the funding shares, etc.

4

payment_hint_title

string

Replace the headline of the payment hint with a custom one.

5

language

string

The locale of the Smart Checkout.

6

submit_button_title

string

Replaces the text of the submit button of the payment page.

7

cancel_button_title

string

Replaces the text of the cancel button of the payment page.

8

hide_disclaimer

boolean

Hides the assignment note. The merchant needs to set has_accepted_disclaimer to enable this functionality.

9

has_accepted_disclaimer

boolean

Needed to unlock hide_disclaimer. ...

Individual Return URLs

The Smart Checkout can return the user to your website. The URLs cover two cases, successful or failed payment. You can define the needed URLs statically in SecuOffice, but you can also pass individual URLs for every particular Smart Transaction. These individual URLs for the Smart Transaction override the static ones from SecuOffice.

Here is an example how to pass both individual return URLs:

{
...
"application_context": {
"return_urls": {
"url_success": "https://www.example.com/survey?x=123",
"url_failure": "https://www.example.com/basket?x=123&r=FAIL"
}
},
...
}

Use secuconnect SDKs

We offer several SDKs to assist you in the integration of our secuconnect API. Currently, PHP, Java and Node JS are available.

The documentation and examples can be found at https://developer.secuconnect.com/.

Further examples and the sources are available at https://github.com/secuconnect.

There packages can also be included using Composer and the Packagist repository (PHP), Gradle (Java), or NPM with or without Browserify (server-side or browser-side JavaScript).

Troubleshooting

Problem

Possible Solution

There are no payment_links in the Smart Transaction.

Please check, whether all preconditions are fulfilled:

  • intent is either sale or authorization;

  • customer is set;

  • payment is not completed yet.

You also need to have an active contract condition for your payment method. There is also a distinction between productive and demo conditions. So you might have no productive or demo conditions active.

There is no payment_links item for a particular payment method.

You need to have an active contract condition for your payment method. There is also a distinction between productive and demo conditions. So the same payment method might be active for productive transactions, but not in demo mode, or vice versa.