This document is intended to support an application developer (hands on technical programmer) during their integration with Magensa services.
\nThe integrating developer should be familiar with the concepts of Restful APIs and have a good understanding of payment device communications.
\nThis set of examples is designed to get a developer up and running quickly. It is not designed to be exhaustive of all possible integration scenarios. For more advanced integrations and other cases not covered here, please contact your assigned solutions architect for information.
\nIn order to fully benefit from the examples provided, the integrating developer should have a Postman account where the collection can be copied to. Create a new Postman account here: https://www.postman.com
\nIntegrated Applications credentials are provisioned for you. Onboarding is a portal / server-to-server operation and is not part of this API — an Integrated Application cannot mint itself a credential or a new refresh token. If you have no credentials, or your refresh token has expired, contact whoever onboarded you.
\nPlease see this collection for the RMS device management for QwantiFi Cloud: QwantiFi Cloud Management
\nEvery request in this collection carries two factors, and both must pass.
\n1. Authorization: Bearer — your current Integrated Applications access token. This is mqttConfig.password from your last issuance or refresh: the same token you place in the MQTT CONNECT password field. It is not a separate API key. It is configured once as collection-level Bearer auth, so every request inherits it — you do not add the header yourself.
2. username and refreshToken in the request body — your Integrated Application username and the opaque refresh token you received at onboarding. The refresh token is verified against a stored salted hash; the platform never holds the plaintext, and it cannot be recovered if you lose it.
Your access token must be unexpired — except on refresh. pos-credentials/refresh accepts an expired token, because replacing an expired credential is exactly what it is for. The three read-only requests reject one with 401. If yours has lapsed, refresh first and retry with the token that comes back.
Keep your last access token even after it expires — it is what you present to refresh. Losing it means you cannot refresh, and there is no self-service way back.
\nA request is rejected when the token's signature does not verify, when its username claim does not match the username in the body, when it has expired (on the three read-only requests), when it was issued more than the refresh-token lifetime ago (90 days by default — this one applies everywhere, including refresh), or when the refresh token is invalid, expired, or revoked. Any failure of either factor returns a single generic 401 with the body { \"error\": \"Unauthorized.\" } and no further detail, by design.
Set posUsername, posRefreshToken, and posAccessToken from the payload you received at onboarding.
Set baseUrl for your environment. To test against the MagTek DEV environment, use https://devgw.magensa.dev/MagensaMQTT.
Run Refresh Access Token first. Its test script writes the new token back into posAccessToken, so the three read-only requests work immediately afterward.
The saved example responses throughout this collection show the MagTek DEV environment. Broker coordinates, reseller and customer ids, and device serials all differ per environment and per account.
\nOnly refresh mints anything. The three Device Discovery requests are strictly read-only: no token is issued and your refresh token is never rotated.
\nRefresh does not rotate your refresh token. refreshToken comes back null on the refresh response — keep using the one you already have. Refreshing on schedule does slide its expiry forward, so an actively-refreshing Integrated Application is never forced back through onboarding.
Your scope is inferred server-side from your stored Integrated Application record — either reseller-wide or a single customer/merchant. You never name a reseller or customer in a request body, and you can only ever see your own devices.
\nErrors are always shaped { \"error\": \"...\" }. 400 means a required field is missing, 401 an authentication failure, 404 a device you do not own or that does not exist, and 503 that the service is temporarily unavailable — retry that one with backoff.
Mints a fresh POS access token from the refresh token you were issued at onboarding — no portal involvement. Present your current access token as Authorization: Bearer alongside your username and refreshToken.
username — your POS username: pos-{resellerId} (reseller-wide) or pos-{resellerId}-{customerId} (customer-scoped).refreshToken — the opaque token returned once at onboarding.200 OK returns status: \"ISSUED\" and a full mqttConfig: broker, port, peerCommonName, qos, username, password, publishTopics, subscribeTopics, operatingMode, and expiresAt.
mqttConfig.password is your new access token — place it in the MQTT CONNECT password field and present it as Authorization: Bearer on subsequent calls. Drive your refresh timer off expiresAt rather than a hard-coded interval; the lifetime is configurable per environment.
refreshToken in the response is always null — the refresh path does not rotate it. Keep using the one you already have.
401. A token issued more than the refresh-token lifetime ago (90 days by default) is refused here too.400 when username or refreshToken is missing. 401 for a missing, malformed, mismatched, or over-age access token, or an invalid, expired, or revoked refresh token. 503 when the service is temporarily unavailable.This request's test script captures mqttConfig.password into the posAccessToken collection variable, so run it first and the rest of the collection is ready to go.
Endpoints in this folder support keeping your POS access token alive without a portal login.
\nUse these requests to:
\nusername and refreshToken, together with your current access token, for a fresh access token and an up-to-date MQTT profile.These requests rely on the following collection variables:
\nbaseUrl — host and virtual path of the gateway.posUsername — your POS username, pos-{resellerId} or pos-{resellerId}-{customerId}.posRefreshToken — the opaque refresh token issued at onboarding.posAccessToken — your current access token. The refresh request rewrites this on success.mqttConfig.publishTopics and mqttConfig.subscribeTopics are recomputed from your current device set, so a refresh doubles as a device-roster refresh.refreshToken in the response is always null.Returns the up-to-date publish and subscribe topics for every device in your scope, without issuing or refreshing anything. Ideal as a periodic poll to discover devices added or removed since your access token was minted.
\nIdentical to Refresh Access Token: username and refreshToken. Your scope is inferred from your stored POS record, so the body names no reseller or customer.
200 OK returns exactly two lists.
publishTopics — one SendCommand topic per device, MagTek/{resellerId}/{customerId}/{deviceSn}/SendCommand. There is deliberately no wildcard entry here: MQTT forbids wildcards in a PUBLISH topic, so commands are always published one device at a time.
subscribeTopics — each device's two event topics (.../device/publish/{deviceSn}/MMSMessage then .../Status), followed by the two scope filters .../device/publish/+/MMSMessage and .../device/publish/+/Status. Subscribe to those two instead of the per-device entries to receive from every device in your scope — including ones onboarded later — in two SUBSCRIBEs.
With no devices in scope, publishTopics is empty and subscribeTopics holds just the two filters.
401. Run Refresh Access Token first and retry with the token it returns.400 when username or refreshToken is missing. 503 when the service is temporarily unavailable.The same per-device information as List Scope Topics, grouped one entry per device. Use this when your POS needs to address a specific device, rather than parsing serials out of topic paths or relying on positional pairing between the two flat lists.
\nIdentical to Refresh Access Token: username and refreshToken. Your scope — reseller-wide or a single customer/merchant — is inferred from your stored POS record, so the body names no entity.
200 OK returns devices, an array of entries:
deviceSn — the device serial number. This is the identifier; key off it.status — the stored lifecycle value, PENDING or PROVISIONED. Devices of both are listed; a PENDING device holds no MQTT credential yet, so its topics are not live.subscribeTopics — exactly two entries, MMSMessage then Status.publishTopic — singular. The one SendCommand topic for this device.nickname — the operator-facing label from the device profile, for display instead of a bare serial. The key is omitted entirely when no nickname is set — never null, never an empty string — so code it as an optional property. It is display text only: not unique, not stable, not an identifier.devices is [] when you own none. A reseller-wide POS sees every customer's devices, each entry's topics carrying that device's own customerId.
publishTopic is singular here while subscribeTopics is plural — a common source of confusion. Each device has exactly one command topic and two event topics.401. Run Refresh Access Token first.Asks whether one specific device is reachable right now, rather than publishing a command and inferring failure from silence. The device serial comes from the URL path, so the body carries only your two authentication values.
\ndeviceSn — the device serial number, maximum 64 characters.Identical to Refresh Access Token: username and refreshToken. Your scope is inferred from your stored POS record.
200 OK returns:
connected — read live from the broker at request time; it is not a stored field. It is also false when the broker's management API is unreachable, so read it as \"not known to be connected\" rather than proof the device is absent.status — the stored lifecycle value, PENDING or PROVISIONED. A PENDING device holds no MQTT credential and so is never connected.blocked — the stored policy flag. A blocked device is banned on the broker.deviceSubscribe — a single topic.devicePublish — two topics, MMSMessage then Status.deviceSubscribe and subscribes to the entries in devicePublish. Read them as \"what the device does\" and your own direction is the opposite.404, with the serial not echoed — so the route cannot be walked to discover which serials exist.401. Run Refresh Access Token first.400 when deviceSn, username, or refreshToken is missing, or deviceSn exceeds 64 characters. 503 when the service is temporarily unavailable.Serial number of the device to inspect. Maximum 64 characters.
\n","type":"text/plain"},"type":"any","value":"DEVSN001","key":"deviceSn"}]}},"response":[{"id":"c7141e30-9e36-4717-8430-36b8ded0b8c1","name":"Get Device Status - 200 OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"username\": \"pos-13204-2026213\",\n \"refreshToken\": \"Endpoints in this folder support read-only lookups of the devices and MQTT topics in your scope.
\nUse these requests to:
\npublishTopics and subscribeTopics, covering every device in your scope plus the two scope-wide subscribe filters.status and optional nickname.connected flag, its stored status and blocked flag, and its topics.These requests rely on the following collection variables:
\nbaseUrl — host and virtual path of the gateway.posUsername — your POS username, pos-{resellerId} or pos-{resellerId}-{customerId}.posRefreshToken — the opaque refresh token issued at onboarding.posAccessToken — your current access token, which must not be expired for these three.deviceSn — the serial number of the device to inspect, used by pos-device-status.401.