NAV Navbar
http

Introduction

Switchpoint is a mobile connectivity platform that enables mobile devices to asynchronously connect to host application via passive NFC tags. A mobile device is regarded as client and the host is most commonly any kind of back-end service.

Switchpoint overview

The SwitchPoint tags are designed and distributed by Ifdef for solution providers. Host and client applications can subscribe to SwitchPoint tags to create data channel between them when applicable.

The following documentation describes the API and flow of the SwitchPoint mobile connectivity platform.

Host API

Authentication

In order to interact with the SwitchPoint api, an authentication token is needed in the header of all requests. The token is distributed by Ifdef.

To call an endpoint you need to add the following headers:

GET /sp/v2/<endpoint> HTTP/1.1
Authorization: Bearer <token>
Host: https://api.ifdef.io

Make sure to replace <token> with your API key.

To use the Switchpoint API the following headers must be added to every API call.

Header Value Description
Authorization Bearer <token> Your private authentication token that identifies you.

Management API

The management API is for partners to manage groups, tags, keys and swish connections.

Login

Login request

POST /sp/v2/auth/login HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded username:password>

Successful response

HTTP/1.1 200 OK
Content-Type: "application/json"

{
    "authentication_token": "<JWT token>"
}

Error response

HTTP/1.1 404 Not Found
Content-Type: "application/json"

{
    "error_code": "40400",
    "error_message": "Resource not found",
    "error_detail": [
        "User not found"
    ]
}

To get a JWT token for the management API the partner needs to login. This endpoints uses basic authentication, and returns JWT token that expires in 2 hours.

POST /sp/v2/auth/login

Create Group

Create a new group

POST /sp/v2/groups HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/json
Authorization: Bearer <Token>

{
    "name": "documentation group"
}

Successful response

HTTP/1.1 201 Created

Create a new group for managing tags

POST /sp/v2/groups

List groups

List all groups

GET /sp/v2/groups HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/json
Authorization: Bearer <Token>

Successful response

HTTP/1.1 200 OK
Content-Type: "application/json"

[
    {
        "id": "216ce76a7fd343e785aa7a0824001111",
        "name": "Example group 1"
    },
    {
        "id": "335306e49d914d9fa284932d9a1a1111",
        "name": "Example group 2"
    }
]

List all existing groups

GET /sp/v2/groups

Add tag to group

Add tag to group

PUT /sp/v2/tags/:tagID HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/json
Authorization: Bearer <token>

{
    "group_id": {
        "value": "<Group ID>"
    }
}

Successful response

HTTP/1.1 200 Ok

Groups are used to group together all tags that share the same swish 123 number, for example all tags within a single store.

PUT /sp/v2/tags/:tagID

Add swishpayment to group

Add swish number to group

POST /sp/v2/groups/:groupID/swish HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/json
Authorization: Bearer token

{
    "swish_123_number": "1234567891"
}

Successful response

HTTP/1.1 200 OK

Swish 123 number needs to be added to a group before a swish payment can be created for a tag within the group.

POST /sp/v2/groups/:groupID/swish`

Parameter Description
groupID The ID of the group the swish 123 number should be added too

Create Keys

Create a new key

POST /sp/v2/keys HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/json
Authorization: Bearer <token>

{
    "level": "PARTNER|GROUP|TAG",
    "id": "<id of the partner|group|tag>",
    "description": "documentation key"
}

Successful response

HTTP/1.1 201 Created
Content-Type: "application/json"
{
    "id": "239448c1a04342f9859cb844b8851111",
    "secret": "ed65665b63e54cc68fa8510715671111"
}

Keys are uses to access the session API

POST /sp/v2/keys`

There are 3 types of keys

Parameter Description
PARTNER Can be used to create a session for all tags owned by the partner
GROUP Can be used to create a session for all tags belonging to the specific group
TAG Can only be used to create a session for a snigle tag

List keys

List all keys

GET /sp/v2/keys HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/json
Authorization: Bearer <token>

Successful response

HTTP/1.1 200 OK
Content-Type: "application/json"
[
    {
        "id": "b862dc93dccb4fd68bc13936dba91111",
        "partner_id": "1D3yKDvSF58mhAOebIqm15N1111",
        "group_id": null,
        "level": "PARTNER",
        "valid": true,
        "description": "documentation key"
    }
]

Lists all keys managed py the partner

GET /sp/v2/keys

Delete key

Delete key

DELETE /sp/v2/keys/:keyID HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/json
Authorization: Bearer <token>

Successful response

HTTP/1.1 204 No Content

A Key can be deleted when no longer needed or if it has been exposed

DELETE /sp/v2/keys/:keyID

Session API

The session API handles all payments and interactions with the switchpoint. To make a payment the host creates a new session towards a specific switchpoint and receives a sessionID. This enables the client to tap on the switchpoint and start the payment process. (See following picture for simplified overview).

Swish flow

Login

Login request

POST /sp/v2/auth/keys/login HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded keyID:keySecret>

Successful response

HTTP/1.1 200 OK
Content-Type: "application/json"

{
    "authentication_token": "<JWT token>"
}

Error response

HTTP/1.1 404 Not Found
Content-Type: "application/json"

{
    "error_code": "40400",
    "error_message": "Resource not found",
    "error_detail": [
        "User not found"
    ]
}

To get a JWT token for the management API a PARTNER|GROUP|TAG needs to login with a key generated with the management API. This endpoints uses basic authentication, and returns JWT token that expires in 1 day.

POST /sp/v2/auth/keys/login

Create Session

Create a session

POST /sp/v2/host/:tagID HTTP/1.1
Host: https://api.ifdef.io
Content-Type: application/json
Authorization: Bearer <token>

{
    "flow": "SWISH",
    "data": {
        "payment_reference": "0123456789",
        "amount":            "100.00",
        "currency":          "SEK",
        "message":           "Kingston USB Flash Drive 8 GB"
    }
}

Successful Response

HTTP/1.1 201 Created
session-id: <sessionID>

The first step in a successful payment is to create a session

POST /sp/v2/host/:tagID

Get Session

Get Session

GET /sp/v2/host/:tagID/session HTTP/1.1
Host: https://api.ifdef.io
session-id: <sessionID>
Authorization: Bearer <token>

Timeout

HTTP/1.1 200 OK
session-id: <sessionID>

{
    "ns": "sp.flow.swish.done",
    "data": {
        "state": "INIT"
    }
}

Session completed

HTTP/1.1 200 OK
session-id: <sessionID>

{
    "ns": "sp.flow.swish.done",
    "data": {
        <Swish payment data>
    }
}

In order to keep the session alive and to receive the session result one Get Session request has to be active at any given time throughout the session. When a request returns the host has 5 seconds to send a new request or the session will be terminated.

The default timout for this request is 60 seconds. In that case the host is free to send a new request to extend the wait time.

Delete Session

Delete session

DELETE /sp/v2/host/:tagID/session HTTP/1.1
Host: https://api.ifdef.io
session-id: <sessionID>
Authorization: Bearer <token>

Successful response

HTTP/1.1 200 OK

Terminates the session immediately, Ongoing 'Get Session' request will return.

Client API

Authentication

Endpoints for the Client API are unauthenticated. However a Session-ID is required to connect through an existing session.

Channels

The client can communicate with the host when the host has initiated a channel. On a successful subscription a Session-ID is received and that Session-ID has to be used for all subsequent communication to that channel instance. A channel instance is closed when the host terminates the connection.

Open channel

Example of a GET request connecting to a channel

GET /blip/v1/client/<tagid> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Host: https://api.ifdef.io

HTTP/1.1 200 OK
Session-ID: <sid>

GET /blip/v1/client/<tagid>

By sending a get request to the endpoint the client connects to a channel given that it has been created by a host. The Session-ID can be read from the headers.

Upon receiving the Session-ID a new GET request should be sent using the Session-ID, that request will return with data from the other end or timeout after 60 seconds

It is the responsibility of the host to send a new GET request upon timeout or receiving data to maintain the channel.

Send data

Send data through the channel using POST request

POST /blip/v1/client/<tagid> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Host: https://api.ifdef.io

{
    "ns": "ifdef.blip.example.channel.post",
    "data": {
        "foo": "bar"
    }
}

Successful response to the POST request

HTTP/1.1 200 OK
Session-ID: <sid>

Data can only be sent after a the client has connected and received a Session-ID.

Make a normal http POST request with the Session-ID in the header.

POST /blip/v1/client/<tagid>

Examples

Flowchart describing roll out of tags and different interactions.

Blip overview

Swish flow

Swish flow

http