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.
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).
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.