To get started with the secuconnect API, we will:

  1. Authenticate with OAuth;
  2. Create a simple Smart Transaction;
  3. 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 authentication is POST /oauth/token.

Request
POST /oauth/token HTTP/1.1
Host: connect-testing.secuconnect.com
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.secuconnect.com
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:

As you can see, it is very easy.