Integration Guide

The former method is deprecated. If you need the guide for legacy implementations, you find it preserved here: Method with Device Registration in secuOffice (Legacy)

Workflow with Device PIN

The workflow with device PIN is this:

Your software once sets the device PIN. Usually this is done by a backoffice system.
Your device authenticates with the device PIN for every new session.

The device PIN can also be changed later the same way it was set in the beginning.

Set the Device PIN

You cannot delete a device PIN so far. Thus it is not possible to get a device back at store level configuration, nor a store at device level configuration, using API calls.

You can set the device PIN either at merchant, store or device level. The closer scope has precedence over the wider. Therefore a device PIN at at store level supersedes one at merchant level, and a device PIN at device level supersedes one at store level.

The device PIN must be at least 15 characters long. It must at contain least characters from 3 of these 4 classes:

Numeric digits
Upper case letters
Lower case letters
Special characters

The characters must not contain repetitions (“AAA”) nor sequences in any order (“abc”, “321”).

Example at Device Level

The endpoint to set the device PIN at device level is PUT /api/v2/Smart/Device/{SDV_xxx}/DevicePin.

Request

POST /api/v2/Smart/Device/SDV_8ZKMSAQ30VNH1WE6EGFJCCG4BCSAML/DevicePin HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "merchant_id": "MRC_CJPC2M1SYRS9WPI4XLIYUUBY6SC9F4",
    "store_id": "STO_0SEWAPM1QV8AZWIC3N0BR5JXESKURO",
    "pin": "CxajtF94uLi4s7d3"
}

If everything is fine, the API responds with 200 OK, and a confirming JSON.

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "result": true
}

If not successful, it responds with 500 Internal Server Error, and the common error response.

Example at Store Level

The endpoint to set the device PIN at store level is the same – but with a store ID (sic!) – PUT /api/v2/Smart/Device/{STO_xxx}/DevicePin.

Request

POST /api/v2/Smart/Device/STO_0SEWAPM1QV8AZWIC3N0BR5JXESKURO/DevicePin HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "merchant_id": "MRC_CJPC2M1SYRS9WPI4XLIYUUBY6SC9F4",
    "store_id": "STO_0SEWAPM1QV8AZWIC3N0BR5JXESKURO",
    "pin": "CxajtF94uLi4s7d3"
}

If everything is fine, the API responds with 200 OK, and a confirming JSON.

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "result": true
}

If not successful, it responds with 500 Internal Server Error, and the common error response.

Example at Merchant Level

The endpoint to set the device PIN at store level is the same – but with a merchant ID (sic!) – PUT /api/v2/Smart/Device/{MRC_xxx}/DevicePin.

Request

POST /api/v2/Smart/Device/MRC_CJPC2M1SYRS9WPI4XLIYUUBY6SC9F4/DevicePin HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "merchant_id": "MRC_CJPC2M1SYRS9WPI4XLIYUUBY6SC9F4",
    "pin": "CxajtF94uLi4s7d3"
}

If everything is fine, the API responds with 200 OK, and a confirming JSON.

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "result": true
}

If not successful, it responds with 500 Internal Server Error, and the common error response.

Read the Device PIN Configuration

You can also check the effective configuration for the device, whether passwords are set at each level.

The endpoint to read the device PIN configuration is GET /api/v2/Smart/Device/{SDV_xxx}/DevicePinConfig.

Request

POST /api/v2/Smart/Device/SDV_8ZKMSAQ30VNH1WE6EGFJCCG4BCSAML/DevicePin HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

If the Smart Device ID is valid, the API responds with 200 OK, and the requested information:

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "merchant": {
        "id": "MRC_CJPC2M1SYRS9WPI4XLIYUUBY6SC9F4",
        "auth_password_set": false
    },
    "store": {
        "id": "STO_0SEWAPM1QV8AZWIC3N0BR5JXESKURO",
        "auth_password_set": true
    },
    "smart_device": {
        "id": "SDV_8ZKMSAQ30VNH1WE6EGFJCCG4BCSAML",
        "auth_password_set": true
    }
}

You cannot read the PIN itself, but you can see at which levels one is set.

Authenticate with Device PIN

The authentication works with the grant type device_pin and the corresponding field for it. It uses the common endpoint POST /oauth/token.

Request

POST /oauth/token HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json
 
{
    "grant_type": "device_pin",
    "client_id": "e3323efa4fb2c4e8562adcdbfe9acf41",
    "client_secret": "44640a4323db70c1b87dcbe27672a997eb98dad04d8e4caf942da70f77841f8d",
    "uuid": "/vendor/ingenico/serial/17275wl26695664",
    "device_pin": "CxajtF94uLi4s7d3"
}

If the Smart Device ID is valid, the API responds with 200 OK, and the wanted tokens:

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "access_token": "7vfogs9bpol1dv2yvl5gqmpl0g",
    "expires_in": 1200,
    "token_type": "bearer",
    "scope": null
}

If not successful, it responds with 400 Bad Request, and a simple error response.