To get started with the secuconnect API, we will:

Authenticate with OAuth;
Create a simple Smart Transaction;
Start Smart Checkout.

If you are not sure if an API integration is the best way to go, please read Integration Options first.

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",
      "address": {
        "street": "Musterstr.",
        "street_number": "55",
        "postal_code": "09123",
        "city": "Musterstadt",
        "country": "DE"
      },
      "email": "max@example.net"
    }
  },
  "intent": "sale",
  "basket_info": {
    "currency": "EUR",
    "sum": 500
  },
  "application_context": {
    "checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
    "language": "de"
  }
}

This will create a Smart Transaction with an amount of €5.00. (Amounts are passed in the minor currency unit.)

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": "Musterhändler GmbH"
    },
    "contract": {
        "object": "general.contracts",
        "id": "GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04"
    },
    "customer": {
        "object": "payment.customers",
        "id": "PCU_WFC7ER68R2PAA5D7DWYR7A9X04ZSAJ",
        "contact": {
            "name": "Max Mustermann",
            "forename": "Max",
            "surname": "Mustermann",
            "salutation": "Herr",
            "email": "max@example.net",
            "address": {
                "street": "Musterstr.",
                "street_number": "55",
                "postal_code": "09123",
                "city": "Musterstadt",
                "country": "DE"
            }
        }
    },
    "created": "2020-02-04T15:34:00+01:00",
    "status": "created",
    "intent": "sale",
    "basket_info": {
        "sum": 500,
        "currency": "EUR"
    },
    "is_demo": true,
    "application_context": {
        "checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
        "language": "de"
    },
    "payment_context": {
        "auto_capture": true,
        "creditcard_schemes": [
            "mastercard",
            "visa",
            "american express",
            "cup"
        ]
    },
    "payment_links": {
        "creditcard": "https://pay-dev.secuconnect.com?payment-method=creditcard&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "debit": "https://pay-dev.secuconnect.com?payment-method=debit&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "eps": "https://pay-dev.secuconnect.com?payment-method=eps&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "giropay": "https://pay-dev.secuconnect.com?payment-method=giropay&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "invoice": "https://pay-dev.secuconnect.com?payment-method=invoice&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "paypal": "https://pay-dev.secuconnect.com?payment-method=paypal&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "prepaid": "https://pay-dev.secuconnect.com?payment-method=prepaid&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "sofort": "https://pay-dev.secuconnect.com?payment-method=sofort&stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "general": "https://pay-dev.secuconnect.com?stx=STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing"
    }
}

The most interesting details are:

id with the ID of the new Smart Transaction object. It is needed for subsequent API calls.
payment_links with some URLs to start our Smart Checkout.

Step 3: Start Smart Checkout

For demonstration, we simply put the URL in payment_links/general into our browser's address bar. This opens Smart Checkout in full screen:

images/download/attachments/197854387/image-2023-11-7_13-35-55-version-1-modificationdate-1699360556000-api-v2.png

As you can see, it is very easy.