Create a session

Before a device can take a payment, the Adyen SoftPOS SDK needs an active session. Your app obtains a setupToken from the SDK, your backend exchanges it here for the sdkData the SDK uses to establish that session, and your app hands sdkData back to the SDK.

The first time a device asks for a session, this call also registers it as a terminal automatically. Straumur identifies each device by its Adyen installation ID (the POIID), so you don't have to set anything up in advance. A merchant or partner can bring as many devices online as they need, simply by calling this endpoint from each one.

Request

POST https://checkout-api.staging.straumur.is/api/v1/taptopay/integrator/sessions

Headers:

X-API-key: YOUR_API_KEY
Content-Type: application/json

Body:

{
    "storeMid": "1234567890",
    "setupToken": "eyJrZXkiOiJ2YWx1ZS013...",
    "deviceModel": "SM-S926B",
    "osVersion": "16",
    "appVersion": "1.4.0"
}

Field	Type		Description
storeMid	String	Required	The MID of the merchant store this session is for. Must be a store your API key is authorized for.
setupToken	String	Required	The opaque setup token produced by the Adyen SoftPOS SDK on the device.
deviceModel	String	Optional	The phone model, as your app reports it. Stored on the device for support.
osVersion	String	Optional	The phone's OS version, as your app reports it.
appVersion	String	Optional	The version of your app on the phone.

Send deviceModel, osVersion and appVersion on every session: they are what Straumur support sees when helping with a device, and appVersion is how you can tell which phones still run an app whose Adyen SDK is about to expire. Field names are case-insensitive, and unknown fields are rejected.

Response

{
    "id": "8615546842023195",
    "installationId": "A8E90121-598F-4553-89E0-B5492AFD9D37",
    "sdkData": "eyJzZGtEYXRhIjoiLi4uIn0=",
    "merchantAccount": "YourMerchantAccount",
    "store": "ST3224Z22322BD5K8JKPJ7TWD",
    "responseDateTime": "2026-10-21T10:15:00Z",
    "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44"
}

Field	Type	Description
id	String	Adyen's identifier for the session.
installationId	String	The device's POIID — its stable Adyen installation id. Keep it: you pass it as poiId when you take a payment.
sdkData	String	The data the SDK needs to finish establishing the session. Pass it to the SDK verbatim.
merchantAccount	String	The Adyen merchant account the session runs under.
store	String	The Adyen store reference.
responseDateTime	DateTime	When Straumur answered (UTC).
responseIdentifier	String	A unique id for this response. Quote it when contacting Straumur support.

Call this endpoint whenever the SDK reports it needs a fresh session (typically at app start or when a session expires).

When to expect errors

Errors return HTTP 400 with errorMessage, errorCode and responseIdentifier (see Errors).

errorCode	errorMessage	When
1005	Could not parse field [{0}]. Expected a {1}.	A field has the wrong JSON type, e.g. setupToken sent as a number.
1006	Unknown field [{0}] in the JSON request body.	The body contains a field this endpoint does not take.
2000	Field [{0}] cannot be empty.	storeMid or setupToken is missing or blank.
2045	Merchant cannot access store or store does not exist. Value: [{0}]	No store with that MID that your key is authorized for. Deliberately the same response whether the store does not exist or is out of scope.
2039	Unable to process due to merchant status - Inactive. Please contact support.	The store's merchant is not active.
2046	Tap to Pay is not enabled for the store. Value: [{0}]	The store's contract is not active, or Tap to Pay is not enabled on it.
2040	Unable to process due to incomplete configuration.	The store is not boarded to Adyen yet.
2047	Tap to Pay device is not active. Value: [{0}]	The device has been disabled. It cannot get a new session, in this or any other store.
2020	Request could not be processed. Please contact support.	Adyen rejected the setupToken or could not provision the session.