Mobile Device Integration#

Guide for mobile app and POS terminal developers integrating with the AuxCORE device API.

Current version: v2.4.0 | Last updated: 2026-10-26 | See Changelog at the end of this page

⚠️ v2.0.0 is a breaking change. The registration flow requires a POST /device/test-connection step before the device becomes active. See Changelog for migration details.

ℹ️ v2.3.0: POST /device/test-connection now validates the merchant gateway configuration the device will use (config only — no processor call, no money moved) and returns a specific failure reason. Its error codes changed — see Test Connection and the Changelog.

🆕 v2.4.0 — multi-merchant support. A user who belongs to several merchants can switch merchant without logging out, and without re-entering TPN + pairing code for a merchant they already registered on. New: GET /device/session, multi-merchant storage contract, and POST /device/logout clarified as Unregister Device — not user sign-out.

Overview#

Mobile apps communicate with the device backend via a dedicated set of endpoints under /api/v1/device. These use device-scoped authentication (a device JWT) rather than user credentials, so the app operates independently after the initial pairing.

Integration Flow#

1.  Admin creates a device in the portal  →  TPN + pairing code, tied to one merchant
2.  Admin shares TPN and pairing code with the device operator

3.  App calls POST /auth/login          →  userJWT
      └─ multi-merchant user → POST /auth/select-merchant  →  userJWT scoped to merchant M

4.  App calls GET /device/session       →  "is my stored token for M still usable?"
      └─ reusable: true                 →  skip to step 7, do NOT ask for TPN
      └─ no stored token, or reusable: false  →  continue to step 5

5.  App calls POST /device/register     →  receives deviceToken (JWT), device status = REGISTERED
6.  App calls POST /device/test-connection  →  validates gateway configuration
                                             →  on success: device status = ACTIVE
      (skipped when step 5 returns nextStep: "none")

7.  App stores deviceToken under merchant M  →  secure storage, keyed by merchantId
8.  App calls GET /device/parameters     →  loads configuration
9.  If posLite.enabled is true, app calls GET /device/products → current branch catalog
10. App calls GET /device/heartbeat periodically  →  detects config changes
11. When paramVersion changes, app calls GET /device/parameters again

12. Switch merchant: POST /auth/switch-merchant  →  new userJWT, then back to step 4

13. If device.paymentAdjustmentType != "NONE", call GET /transactions/fee-preview before
    displaying price to customer  →  always use server-computed price, never calculate in app
14. Before each sale in dual-pricing mode (pricingModel = cashdiscount), call
    GET /transactions/fee-preview  →  displays cash / credit / ACH prices

The login/session and merchant-switching portions are the v2.4.0 flow. The session check is what
removes the repeated TPN prompt — see Multi-merchant device storage.

Dual pricing (cash / credit / ACH display)#

Merchants in dual-pricing mode (pricingModel: cashdiscount) require the POS to show posted cash price and credit (card) price before payment — a compliance requirement in states such as New York. AuxCORE computes these server-side; do not calculate adjustments in the app.

Use the prices.cash, prices.card, and prices.ach objects from the response. When dualPricingRequired is true, all three labels must be shown when ACH is enabled.

Full reference: Fee Preview API

Device Status Lifecycle#

Admin creates device
       │
       ▼
   PENDING  ──── App calls /register ────►  REGISTERED  ──── /test-connection pass ────►  ACTIVE
      │                                         │                                              │
      │ admin disable                     re-register ok                               admin disable
      ▼                                   (refresh token)                                     ▼
   INACTIVE  ◄────────────────────────────────────────────────────────────────────────  INACTIVE
      │                                                                                        │
      └──────────────────────── admin suspend ────────────────────────────────────────►  SUSPENDED

There is no separate UNREGISTERED status — unregistering a device puts it in INACTIVE, from which it can be registered again with the same TPN + pairing code.

Multi-merchant device storage#

A merchant user may belong to several merchants and register a different device at each. Each Device has its own TPN + Pairing Code, and after registration the Device becomes Active.

The app owns the memory of which device belongs to which merchant. Store a map in secure storage:

merchantId → deviceToken

Rules the app must follow:

The server never picks a device for the app. GET /auth/my-merchants reports deviceRegistration.hasActiveDevice per merchant so the picker can show which merchants still need a TPN — that is a display hint; GET /device/session is the authority.

Recovering a lost token. If the app is reinstalled or storage is cleared, register again with the same TPN + pairing code. The device is still ACTIVE, and re-registration is allowed for the user who registered it originally — no admin action needed. A different user gets 400 Device already registered.

Typical merchant-switch sequence#

GET  /api/v1/auth/my-merchants            → list + hasActiveDevice per merchant
POST /api/v1/auth/switch-merchant {B}     → new access token scoped to Merchant B
GET  /api/v1/device/session               → with the stored device token for B
        reusable: true   → go to Home / Payment
        reusable: false  → show Device Registration (TPN + pairing code)

Base URL#

https://uat.auxcore.net

Authentication#

Required Headers (All Requests)#

Dual-Header Pattern#

The mobile app uses two separate headers for two separate concerns:

Step 1 — Registration#

Requires a user JWT (merchant user must be logged in via POST /api/v1/auth/login).

Authorization: Bearer <user_jwt>
X-Tenant-ID: your-tenant-id

Step 2 — Device-Only Endpoints (/device/me, /device/parameters, /device/heartbeat)#

Require both headers — user JWT for identity + device token for device context.

Authorization: Bearer <user_jwt>
X-Device-Token: <device_token>
X-Tenant-ID: your-tenant-id

Store the deviceToken in secure on-device storage (Android Keystore / iOS Keychain). This token does not expire on a timer — it stays valid until the device is suspended, deleted, or re-paired.

Step 3 — Payment & Notification APIs (/transactions/*, /payment-links, etc.)#

Send both headers. The user JWT authenticates the call; the device token enriches it with device context (device-level credentials, limits, transaction type restrictions).

Authorization: Bearer <user_jwt>
X-Device-Token: <device_token>
X-Tenant-ID: your-tenant-id

Important: If X-Device-Token is included, it must be valid. An invalid or revoked device token returns 401 (a suspended device returns 403 DEVICE_SUSPENDED) even if the user JWT is valid. Omit the header entirely for calls that do not originate from a registered device (e.g. Virtual Terminal use cases).

On payment APIs the device token is checked for a live session and a non-suspended device only — the ACTIVE status is not re-checked there, so gate payments in the app on a successful test-connection / GET /device/session.

Header Summary by Endpoint#

Endpoints#

{
  "success": true,
  "data": {
    "currentMerchantId": "merchant_123",
    "merchants": [
      {
        "merchantId": "merchant_123",
        "companyName": "Acme Coffee",
        "role": "merchant_admin",
        "status": "active",
        "deviceRegistration": {
          "hasActiveDevice": true,
          "activeDeviceCount": 1,
          "device": {
            "deviceId": "550e8400-e29b-41d4-a716-446655440001",
            "deviceLabel": "Counter 1",
            "tpnLast4": "4651",
            "status": "ACTIVE",
            "lastActiveAt": "2026-08-10T09:14:02.000Z"
          }
        }
      }
    ]
  }
}

curl -X POST "https://uat.auxcore.net/api/v1/auth/switch-merchant" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "merchantId": "merchant_456" }'

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "Qm9vZ3VzUmVmcmVzaFRva2VuRXhhbXBsZQ...",
    "tokenType": "Bearer",
    "expiresIn": 86400,
    "user": {
      "id": "8d2f6b1e-4a7c-4c1e-9b3a-2f5e6d7c8a90",
      "email": "cashier@example.com",
      "fullName": "Jane Cashier",
      "role": "merchant_admin",
      "merchantId": "merchant_456",
      "mfaEnabled": false,
      "permissions": ["transactions.view", "transactions.refund"]
    },
    "features": { "invoicing": true },
    "navigation": []
  }
}

curl -X POST "https://uat.auxcore.net/api/v1/device/register" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "tpn": "483920174651",
    "pairingCode": "619274",
    "appVersion": "2.1.0",
    "osVersion": "14.0",
    "osPlatform": "ANDROID"
  }'

{
  "success": true,
  "data": {
    "device": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "tenantId": "your-tenant-id",
      "merchantId": "merchant_123",
      "branchId": "branch-456",
      "deviceLabel": "Drive-Thru Terminal",
      "deviceNumber": 1042,
      "tpn": "483920174651",
      "manufacturer": "ANDROID_PHONE",
      "deviceType": "TAP_ON_PHONE",
      "paymentMode": "NEARPAY",
      "merchantGatewayId": null,
      "gateway": null,
      "templateId": null,
      "mid": null,
      "terminalId": null,
      "iposTpn": null,
      "iposTpnCode": null,
      "nearpayTid": "TID-NP-001",
      "sunmiSN": null,
      "paymentAdjustmentType": "FLAT",
      "paymentAdjustmentValue": "1.5000",
      "paymentAdjustmentCardValue": "2.0000",
      "paymentAdjustmentAchValue": "0.5000",
      "autoSettleEnabled": true,
      "settleAt": "17:00",
      "status": "REGISTERED",
      "skipTestConnection": false,
      "pairingCode": "619274",
      "appVersion": "2.2.0",
      "osVersion": "14.0",
      "osPlatform": "ANDROID",
      "registeredAt": "2026-04-14T10:00:00.000Z",
      "registeredByUserId": "8d2f6b1e-4a7c-4c1e-9b3a-2f5e6d7c8a90",
      "assignedUserId": null,
      "isShared": true,
      "lastActiveAt": "2026-04-14T10:00:00.000Z",
      "txCount": 0,
      "txVolumeUsd": "0.00",
      "createdBy": "3b9e1c22-7d4f-4e8a-a1b2-c3d4e5f6a7b8",
      "updatedBy": null,
      "createdAt": "2026-04-10T00:00:00.000Z",
      "updatedAt": "2026-04-14T10:00:00.000Z",
      "deletedAt": null
    },
    "deviceToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "jwtNearpayDevice": "eyJhbGciOiJSUzI1NiJ9...",
    "nextStep": "test-connection",
    "testConnectionRequired": true
  }
}

Authorization: Bearer <user_jwt>
X-Device-Token: <device_token>
X-Tenant-ID: your-tenant-id

curl -X POST "https://uat.auxcore.net/api/v1/device/test-connection" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "message": "Connection validated successfully",
  "data": {
    "deviceId": "550e8400-e29b-41d4-a716-446655440001",
    "status": "ACTIVE",
    "gatewayType": "TsysSierra",
    "configStatus": "VALID",
    "processorStatus": "CONNECTED",
    "validatedAt": "2026-06-25T10:30:00Z",
    "testDurationMs": 142
  },
  "timestamp": "2026-06-25T10:30:00Z"
}

{
  "success": true,
  "message": "Device is already active — no test-connection required",
  "data": { "deviceId": "550e8400-...", "status": "ACTIVE", "alreadyActive": true }
}

{
  "success": false,
  "error": "GATEWAY_NOT_CONFIGURED",
  "message": "No active TsysSierra gateway is configured for this merchant",
  "userMessage": "No active TsysSierra gateway is configured for this merchant",
  "code": 422,
  "retryable": false,
  "reason": "NO_ACTIVE_GATEWAY",
  "gatewayType": "TsysSierra",
  "timestamp": "2026-06-25T10:30:00Z"
}

{
  "success": true,
  "data": {
    "reusable": true,
    "status": "ACTIVE",
    "device": { "id": "550e8400-...", "deviceLabel": "Drive-Thru Terminal", "status": "ACTIVE", "...": "full device object, as in /device/register" }
  }
}

{
  "success": true,
  "data": {
    "reusable": false,
    "reason": "NOT_ACTIVE",
    "status": "INACTIVE",
    "device": { "id": "550e8400-...", "status": "INACTIVE" }
  }
}

curl "https://uat.auxcore.net/api/v1/device/session" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id"

Authorization: Bearer <user_jwt>
X-Device-Token: <device_token>
X-Tenant-ID: your-tenant-id

curl "https://uat.auxcore.net/api/v1/device/me" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "tenantId": "your-tenant-id",
    "merchantId": "merchant_123",
    "branchId": "branch-456",
    "deviceLabel": "Drive-Thru Terminal",
    "deviceNumber": 1042,
    "tpn": "483920174651",
    "manufacturer": "ANDROID_PHONE",
    "deviceType": "TAP_ON_PHONE",
    "paymentMode": "NEARPAY",
    "merchantGatewayId": null,
    "gateway": null,
    "templateId": null,
    "mid": null,
    "terminalId": null,
    "iposTpn": null,
    "iposTpnCode": null,
    "nearpayTid": "TID-NP-001",
    "sunmiSN": null,
    "paymentAdjustmentType": "FLAT",
    "paymentAdjustmentValue": "1.5000",
    "paymentAdjustmentCardValue": "2.0000",
    "paymentAdjustmentAchValue": "0.5000",
    "autoSettleEnabled": true,
    "settleAt": "17:00",
    "status": "ACTIVE",
    "skipTestConnection": false,
    "pairingCode": "619274",
    "appVersion": "2.2.0",
    "osVersion": "14.0",
    "osPlatform": "ANDROID",
    "registeredAt": "2026-04-14T10:00:00.000Z",
    "registeredByUserId": "8d2f6b1e-4a7c-4c1e-9b3a-2f5e6d7c8a90",
    "assignedUserId": null,
    "isShared": true,
    "lastActiveAt": "2026-06-16T10:30:00.000Z",
    "txCount": 42,
    "txVolumeUsd": "3810.00",
    "createdBy": "3b9e1c22-7d4f-4e8a-a1b2-c3d4e5f6a7b8",
    "updatedBy": null,
    "createdAt": "2026-04-10T00:00:00.000Z",
    "updatedAt": "2026-06-16T10:30:00.000Z",
    "deletedAt": null,
    "nearpayJWT": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

curl "https://uat.auxcore.net/api/v1/device/parameters" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": {
    "version": 7,
    "signatureThreshold": "0.00",
    "isViewAllMerchantTransaction": false,
    "transactions": {
      "saleEnabled": true,
      "refundEnabled": true,
      "voidEnabled": true,
      "preauthEnabled": false
    },
    "requirePin": {
      "pinVoidEnabled": false,
      "pinRefundEnabled": true
    },
    "paymentTypes": {
      "tapToPayEnabled": true,
      "keyedInEnabled": false,
      "qrCodeEnabled": false,
      "paymentLinkEnabled": false,
      "achTransferEnabled": false,
      "cashEnabled": true
    },
    "limits": {
      "perTransaction": "500.00",
      "daily": "5000.00",
      "weekly": null,
      "monthly": null
    },
    "receipt": {
      "headerMsg": "Welcome!",
      "footerMsg": "Thank you!",
      "disclaimer": null,
      "autoPrintEnabled": true,
      "printMerchantCopy": true,
      "smsEnabled": true,
      "emailEnabled": true,
      "signatureCapture": false
    },
    "posLite": {
      "enabled": true
    },
    "productCart": {
      "enabled": true
    },
    "tips": {
      "allowTips": true,
      "presets": [10, 15, 20, 25],
      "maxAmount": "100.00",
      "maxPercentage": 30
    },
    "tax": {
      "enabled": true,
      "enableRemove": false,
      "removePasswordProtected": false,
      "tax1": { "label": "Sales Tax", "value": "8.25" },
      "tax2": { "label": null, "value": null }
    },
    "inputFields": [
      {
        "key": "billing_name",
        "label": "Cardholder Name",
        "group": "general",
        "type": "text",
        "display": true,
        "required": true,
        "order": 1
      }
    ],
    "shipping": {
      "enabled": false,
      "sameAsBillingVisible": false
    }
  }
}

curl "https://uat.auxcore.net/api/v1/device/heartbeat" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": {
    "paramVersion": 7,
    "serverTime": "2026-04-14T10:30:00.000Z"
  }
}

App startup:
  1. GET /device/parameters  →  store locally with version = 7

Every N minutes:
  2. GET /device/heartbeat  →  returns { paramVersion: 8 }
  3. If paramVersion != local version:
       GET /device/parameters  →  refresh local config

Authorization: Bearer <user_jwt>
X-Device-Token: <device_token>
X-Tenant-ID: your-tenant-id

curl -X POST "https://uat.auxcore.net/api/v1/device/logout" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": {
    "message": "Device logged out"
  }
}

Token Lifecycle#

When the Token is Revoked#

The device JWT becomes invalid in the following situations:

An admin deactivating a device now revokes its sessions immediately — the stored token stops working the moment the device leaves ACTIVE, it is not merely blocked at the route.

Detecting Revocation#

When the token is revoked, all device API calls (/device/session, /device/me, /device/parameters, /device/heartbeat, /device/logout, /device/test-connection) return:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Device token has been revoked"
  }
}

message is one of "Device token is required in X-Device-Token header", "Invalid device token", "Invalid token type", "Device session not found", "Device token has been revoked" or "Device not found".

HTTP Status: 401 Unauthorized

Your app should catch 401 responses on device endpoints, clear the stored deviceToken, and present the registration screen to the operator.

For payment APIs (/transactions/*, etc.) where X-Device-Token was included, a revoked or unknown device token returns the same 401 UNAUTHORIZED body as above. A token that cannot be decoded at all returns:

{
  "success": false,
  "error": {
    "code": "INVALID_DEVICE_TOKEN",
    "message": "Device token is malformed"
  }
}

If the device token cannot be checked because the merchant service is unreachable, payment APIs return 503 SERVICE_UNAVAILABLE ("Could not validate device token") — retry. POST /merchants/verify-pin reports every invalid device token as 401 INVALID_DEVICE_TOKEN.

HTTP Status: 401 Unauthorized — treat the same way: clear token, show registration screen.

Implementation Guide#

Android#

// Store device token securely
val sharedPreferences = EncryptedSharedPreferences.create(
    "device_prefs",
    MasterKey.DEFAULT_MASTER_KEY_ALIAS,
    context,
    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
)
sharedPreferences.edit().putString("device_token", deviceToken).apply()

// Device-only endpoints (me, parameters, heartbeat) — use both headers
val userJwt = sharedPreferences.getString("user_jwt", null)
val deviceToken = sharedPreferences.getString("device_token", null)
val deviceRequest = Request.Builder()
    .url(deviceEndpointUrl)
    .addHeader("Authorization", "Bearer $userJwt")
    .addHeader("X-Device-Token", deviceToken ?: "")
    .addHeader("X-Tenant-ID", tenantId)
    .build()

// Payment/notification endpoints — use both headers
val userJwt = sharedPreferences.getString("user_jwt", null)
val paymentRequest = Request.Builder()
    .url(transactionUrl)
    .addHeader("Authorization", "Bearer $userJwt")
    .addHeader("X-Device-Token", deviceToken ?: "")
    .addHeader("X-Tenant-ID", tenantId)
    .build()

iOS (Swift)#

// Store device token in Keychain
let tokenData = deviceToken.data(using: .utf8)!
let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrAccount as String: "device_token",
    kSecValueData as String: tokenData
]
SecItemAdd(query as CFDictionary, nil)

// Device-only endpoints (me, parameters, heartbeat) — use both headers
var deviceRequest = URLRequest(url: deviceEndpointURL)
deviceRequest.setValue("Bearer \(userJwt)", forHTTPHeaderField: "Authorization")
deviceRequest.setValue(deviceToken, forHTTPHeaderField: "X-Device-Token")
deviceRequest.setValue(tenantId, forHTTPHeaderField: "X-Tenant-ID")

// Payment/notification endpoints — use both headers
var paymentRequest = URLRequest(url: transactionURL)
paymentRequest.setValue("Bearer \(userJwt)", forHTTPHeaderField: "Authorization")
paymentRequest.setValue(deviceToken, forHTTPHeaderField: "X-Device-Token")
paymentRequest.setValue(tenantId, forHTTPHeaderField: "X-Tenant-ID")

Startup Checklist#

Implement the following sequence when your app launches:

1. Read userJWT + devices{} map from secure storage
   └─ userJWT not found / expired → show Login screen
   └─ Resolve the active merchantId M from the userJWT

2. GET /device/session   (can I reuse the token stored for M?)
   Headers: Authorization: Bearer <userJWT>  +  X-Device-Token: devices[M]
   └─ devices[M] missing     → show Registration screen (enter TPN + pairing code)
   └─ 401 on userJWT         → refresh JWT first (POST /auth/refresh), retry
   └─ 401 / 403 on device    → delete devices[M], show Registration screen
   └─ reusable: false        → delete devices[M], show Registration screen
                               (reason NOT_ACTIVE / CONTEXT_MISMATCH /
                                REGISTERED_BY_ANOTHER_USER / DEVICE_NOT_FOUND)
   └─ reusable: true         → continue to step 3, do NOT prompt for TPN

3. GET /device/parameters  (load or refresh config)
   Headers: Authorization: Bearer <userJWT>  +  X-Device-Token: devices[M]
   └─ Store paramVersion locally

4. Refresh userJWT if needed
   └─ POST /auth/refresh with refreshToken
   └─ The refreshed token keeps merchant M — no need to re-select
   └─ Store new userJWT in secure storage

5. Start heartbeat loop (every 60–120s)
   Headers: Authorization: Bearer <userJWT>  +  X-Device-Token: devices[M]
   └─ GET /device/heartbeat
   └─ If paramVersion changed → GET /device/parameters
   └─ If 401 → delete devices[M], prompt re-registration
   └─ If 403 DEVICE_NOT_ACTIVE → navigate to Test Connection screen

6. For payment operations (transactions, payment-links):
   └─ Send both: Authorization: Bearer <userJWT>  +  X-Device-Token: devices[M]
   └─ If 401 UNAUTHORIZED / INVALID_DEVICE_TOKEN on the device token → delete devices[M], prompt re-registration
   └─ If 401 on userJWT (TOKEN_EXPIRED) → refresh JWT, retry once
   └─ If 403 DEVICE_SUSPENDED → show suspended screen
   └─ If 503 SERVICE_UNAVAILABLE → device check unavailable, retry

7. On merchant switch:
   └─ GET /auth/my-merchants          (list + hasActiveDevice badge per merchant)
   └─ POST /auth/switch-merchant      → store the new userJWT, M becomes the new merchant
   └─ Go back to step 2 with devices[new M]
   └─ Do NOT touch the device of the merchant being left — it stays ACTIVE

8. On user sign-out:
   └─ Clear userJWT + refreshToken only
   └─ KEEP the devices{} map — signing out does not release any device
   └─ Do NOT call POST /device/logout
   └─ Navigate to Login screen
       (next login re-enters each merchant without a TPN prompt)

9. On "Unregister this device" (explicit user action only):
   └─ POST /device/logout  (both headers — requires ACTIVE status)
   └─ Delete devices[M] from the map
   └─ (Device is now INACTIVE — re-register with the same TPN + pairing code to reactivate)

Steps 8 and 9 replace the old single "On user logout" step. Previously the checklist told the app to call /device/logout and clear the token at sign-out; doing that now breaks the reuse behaviour, because the device drops to INACTIVE and the next login has to ask for the TPN again.

Entering a merchant (first time and every time after)#

The same path runs on first launch, after sign-in, and after every merchant switch. Only the left branch prompts for a TPN.

App start / sign-in / merchant switch
         │
         ▼
  POST /auth/login  (+ /auth/select-merchant if multi-merchant)
  or POST /auth/switch-merchant          →  userJWT scoped to merchant M
         │
         ▼
  devices[M] in secure storage?
         │
    ┌────┴─────────────────────┐
   no                         yes
    │                          │
    │                          ▼
    │                 GET /device/session
    │                          │
    │           ┌──────────────┴──────────────┐
    │      reusable: false               reusable: true
    │      401 / 403                          │
    │           │                             │
    │  delete devices[M]                      │
    ▼           ▼                             │
  Registration screen → enter TPN + pairing code
         │                                    │
         ▼                                    │
  POST /device/register                       │
         │                                    │
         ├─ Error → show message + retry      │
         │                                    │
         ▼                                    │
  nextStep == "test-connection" ?             │
         │                                    │
    ┌────┴────┐                               │
   yes        no                              │
    │         │                               │
    ▼         │                               │
  POST /device/test-connection                │
    │         │                               │
  ┌─┴──┐      │                               │
 Pass Fail    │                               │
  │    └→ show error + Retry                  │
  ▼         │                                 │
 status = ACTIVE                              │
  │         │                                 │
  └────┬────┘                                 │
       ▼                                      │
  store devices[M] = deviceToken              │
       │                                      │
       └──────────────┬───────────────────────┘
                      ▼
        Main Dashboard (ready for payments)

Error Reference#

Standard Error Format#

Device controller errors (register, me, parameters, heartbeat, logout, session) use a flat body:

{
  "success": false,
  "message": "Human-readable description"
}

Route guards (device token, device status, user JWT) and the transaction service use a nested body — branch on error.code:

{
  "success": false,
  "error": { "code": "DEVICE_NOT_ACTIVE", "message": "Device is not yet activated. Complete test-connection first." }
}

POST /device/test-connection uses its own flat body with error, message, code (HTTP status) and retryable — see Test Connection.

Common Errors#

Device Parameter Reference#

Top-level fields#

transactions Section#

requirePin Section#

paymentTypes Section#

limits Section#

All values are decimal strings (e.g. "500.00") or null (no limit).

tips Section#

tax Section#

receipt Section#

posLite Section#

Configured per device by the merchant or an admin (Locations & Devices → device → Edit Parameters →
Transactions tab → Device → POS Lite). Changing it bumps version, so the heartbeat tells the app
to re-fetch.

productCart carries the same enabled value under the section's former name. It is deprecated:
read posLite; productCart is kept only for app builds released before the rename.

inputFields Section#

Each entry in inputFields describes a field on the payment form:

Only render fields where display: true. Enforce required: true fields on form submission.

When the merchant saves their Field Config, the device column (terminals) or mobile column (phones) is applied
here: a required field becomes display: true, required: true, locked: true, a field switched off becomes
display: false. Billing Address drives the avs group; Shipping Address is not applicable to devices and leaves
the shipping group as configured per device.

Payment Flow by Device Type#

The combination of manufacturer, deviceType, and paymentMode (from /device/register or /device/me) determines the payment UI and SDK behavior:

NearPay SDK initialization#

When paymentMode = "NEARPAY":

1. From POST /device/register → read data.jwtNearpayDevice.
2. From GET /device/me → read data.nearpayJWT (same RS256 token, different key name).
3. Read nearpayTid from the device object.
4. Initialize: NearPay.init(tid: nearpayTid, jwt: <jwtNearpayDevice|nearpayJWT>).

Persist whichever JWT you receive and reuse it until it expires or the device re-registers.

Price adjustment display#

When paymentAdjustmentType != "NONE", call GET /transactions/fee-preview before showing the price — always display the server-computed amount, never calculate the adjustment in the app. See Dual pricing.

Payment & Notification APIs from Device#

After device registration, the mobile app calls standard payment APIs using both headers. The server uses the device token to apply device-level rules and record which device processed each transaction.

Calling a Transaction#

curl -X POST "https://uat.auxcore.net/api/v1/transactions/sale" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "merchant_123",
    "amount": 125.00,
    "currency": "USD",
    "pciToken": "pci_tok_9f2c4e7a1b3d"
  }'

When X-Device-Token is present, the server:

• Enforces device parameter limits (perTransaction, plus daily / weekly / monthly volume) — 422 LIMIT_EXCEEDED
• Validates the transaction type is enabled on this device (saleEnabled, preauthEnabled, refundEnabled, voidEnabled) — 403 TX_TYPE_DISABLED
• Rejects ACH sales when achTransferEnabled is off — 403 PAYMENT_TYPE_DISABLED
• Records the deviceId and the device's location (branchId, branchName) on the transaction for audit and reporting

Gateway routing still uses the merchant's gateway configuration; the device's mid / terminalId are only stamped on transactions recorded through POST /transactions/external-payment.

curl -X POST "https://uat.auxcore.net/api/v1/transactions/sale" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "merchant_123",
    "amount": 21.65,
    "baseAmount": 20.00,
    "taxAmount": 1.65,
    "tipAmount": 0,
    "currency": "USD",
    "paymentMethod": "Cash"
  }'

curl -X POST "https://uat.auxcore.net/api/v1/transactions/external-payment" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "gatewayTransactionId": "NP-7781203345",
    "paymentMode": "NEARPAY",
    "amount": 54.00,
    "baseAmount": 50.00,
    "tipAmount": 4.00,
    "cardLast4": "4242",
    "cardBrand": "Visa"
  }'

Itemised sales (POS cart)#

For the focused, shareable five-endpoint request contract and Postman verification matrix, see
POS Itemised Payment Contract.

A sale may carry the cart it sold, so the transaction detail and the receipt list the items and the
products count toward "most sold" (see Product Catalog, section "Tiles").
Send lineItems on any of:

• POST /transactions/sale (card and cash) and POST /transactions/auth
• POST /transactions/token-sale
• POST /transactions/ach-sale
• POST /transactions/external-payment (IPOS / NearPay)

Without lineItems a sale works exactly as before.

This type belongs to the transaction line, not the catalog item. A catalog-backed row uses
type: "product" plus its productId whether GET /device/products returned catalog type
product or service; the server resolves the catalog type during preflight, and a service never
tracks inventory. Reserve type: "misc" for a free-text till row with no productId. Do not send
type: "service" in lineItems.

Rules:

• At most 200 lines. An empty array is the same as no cart.
• The lines must add up to the sale's baseAmount — the amount before tip, tax and convenience fee — within $0.01. Send baseAmount explicitly, or the server derives it as amount - tipAmount - taxAmount - convenienceFee.
• A misc line ("Miscellaneous": a name and an amount typed at the till) is stored on the sale only. It never creates a catalog product and never counts toward most sold.
• The lines are a snapshot: editing or deleting the product later does not change the sale.
• Product quantities are aggregated across duplicate lines and checked against active catalog
  state, maxQuantity, the current device branch, inventory policy, and server-calculated
  Available. Card/cash sale, token sale, AUTH, and ACH submission fail closed before payment when
  validation rejects the cart or the Invoice service is unavailable.
• allowZeroStockSale: false rejects insufficient Available before payment. With
  allowZeroStockSale: true, Available 2 and quantity 5 can complete: inventory records deducted 2,
  not deducted 3, and Available 0. The not-deducted 3 is immutable history; later Quantity In does
  not consume it.
• Service, misc, and untracked product lines need no stock location. A tracked product requires the
  device's current active physical branch; pairing can remain valid even when that branch is absent.

curl -X POST "https://uat.auxcore.net/api/v1/transactions/sale" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "merchant_123",
    "amount": 19.98,
    "baseAmount": 18.48,
    "taxAmount": 1.50,
    "paymentMethod": "Cash",
    "lineItems": [
      { "productId": "3f2b8c1e-4d5a-4e6f-8a7b-9c0d1e2f3a4b", "name": "Diesel", "quantity": 2.5, "unit": "gallon", "unitPrice": 4.19 },
      { "type": "misc", "name": "Car wash", "quantity": 1, "unitPrice": 8.00 }
    ]
  }'

The transaction returned (and GET /transactions/:id) carries the normalised cart:

"lineItems": [
  { "type": "product", "productId": "3f2b8c1e-...", "name": "Diesel", "quantity": 2.5, "unit": "gallon", "unitPrice": 4.19, "lineTotal": 10.48 },
  { "type": "misc", "productId": null, "name": "Car wash", "quantity": 1, "unit": null, "unitPrice": 8, "lineTotal": 8 }
]

The transaction list (GET /transactions) does not include lineItems; read them from the
detail. Email, printed and PDF receipts list the items; the SMS receipt does not.

Errors are 400 INVALID_LINE_ITEMS, checked before the card is charged. The message names the line
("lineItems[1]: quantity must have at most 3 decimal places") and error.details.line carries its
index; a total mismatch reports details.lineItemsTotal and details.baseAmount.

A cart over a product's per-order limit is 400 QUANTITY_LIMIT_EXCEEDED, also before any charge:

{
  "success": false,
  "error": {
    "code": "QUANTITY_LIMIT_EXCEEDED",
    "message": "\"Diesel\" is limited to 50 per order",
    "details": {
      "violations": [
        {
          "code": "QUANTITY_LIMIT_EXCEEDED",
          "productId": "3f2b8c1e-...",
          "message": "\"Diesel\" is limited to 50 per order",
          "maxQuantity": 50,
          "requested": 60
        }
      ]
    }
  }
}

For external-payment, send lineItems with the device's fee breakdown. If the provider webhook
already created the transaction, the cart is added to it. Because the money already exists, a
failed inventory preflight preserves the financial record; when an external SALE reaches a final
approved/settled status, the server queues inventory work when POS settlement is enabled. Once
Invoice accepts that work, unresolved stock or location outcomes become Pending Review. A terminal
delivery failure remains operational outbox work and never changes the payment result.

Payment finality and inventory#

The inventory effects below assume the server-side POS inventory settlement rollout is enabled.
The mobile client cannot read or control that setting and must not treat payment success as proof
of a completed stock deduction.

Payment remains successful if inventory delivery or application fails. Staff can retry Invoice
Pending Review or correct a missing/inactive physical location; operational staff handle terminal
Transaction outbox failures separately. These actions are idempotent and must never create a
replacement payment. Physical returns require a separate Quantity In movement with Customer Return
reason. Refresh the device product catalog after a completed sale.

Querying Transactions from a Device#

curl "https://uat.auxcore.net/api/v1/transactions" \
  -H "Authorization: Bearer USER_JWT_HERE" \
  -H "X-Device-Token: DEVICE_TOKEN_HERE" \
  -H "X-Tenant-ID: your-tenant-id"

When X-Device-Token is present, results are filtered to this device only — unless the device parameter isViewAllMerchantTransaction is true, in which case they cover the whole merchant. Without the device token, results include all transactions for the merchant.

Related#

• Device Management (Portal API) →
• Authentication →
• Error Codes →

Changelog#

For mobile developers: This section tracks breaking changes, new endpoints, and behavior changes that require app updates. Review each entry before upgrading your integration.

v2.5.2 — 2026-10-14 — Field Config reaches the right device fields#

Type: Value fix — no change to the response shape.

• A merchant's Field Config now sets inputFields by the field catalog: Billing Address drives the avs_* fields (it used to drive shipping_*), Customer Name drives customer_name, and Shipping Address no longer touches shipping.enabled or the shipping_* fields. Values change on a device the next time the merchant saves Field Config, and the bumped version makes the heartbeat re-fetch.
• locked (already sent on some entries) is now documented.

v2.5.1 — 2026-10-14 — Product cart renamed POS Lite#

Type: Rename — no breaking change.

• GET /device/parameters returns the cart switch as posLite.enabled. productCart.enabled still returns the same value but is deprecated; read posLite.

v2.5.0 — 2026-10-14 — POS product cart (TNEW-350)#

Type: New optional fields — no breaking change.

• GET /device/parameters returns productCart.enabled (default true): show or hide the cart.
• Sales accept an optional lineItems cart (product and misc lines, decimal quantities) — see "Itemised sales (POS cart)" above. It is validated against baseAmount, stored on the transaction, shown on the portal and printed on email / print / PDF receipts.
• GET /products adds isFavorite, soldQuantity, unit / unitLabel, the favorite filter, sort, and view=most_sold for the tile view — see Product Catalog. Favorites and units are set by the merchant in the web portal; the app only reads them.

v2.4.0 — 2026-08-10 — Merchant switching without re-entering TPN#

Type: New endpoints + behavior change
Affects: apps whose users belong to more than one merchant

What changed#

A user can now switch merchant without logging out, and returns to a merchant they previously registered on without re-entering TPN + Pairing Code — as long as that device is still ACTIVE.

Required app changes#

1. Store merchantId → deviceToken, not a single token. See Multi-merchant device storage.
2. Do not call POST /device/logout on user sign-out. That endpoint unregisters the device and sets it INACTIVE, which breaks the "sign out then sign back in without a TPN prompt" behaviour. Keep the stored map across sign-out.
3. After switching merchant, call GET /device/session before deciding whether to show Device Registration.
4. Replace the startup GET /device/me probe with GET /device/session — /device/me answers 403 for a device that is merely inactive, which is an error path rather than a decision signal.

Documentation corrected in this release#

The Startup Checklist previously instructed the app to call POST /device/logout and clear the stored token on user sign-out. That guidance is now wrong and has been split into two separate steps — sign-out (step 8, keeps everything) and Unregister Device (step 9, the only step allowed to call /device/logout). The Integration Flow and the entry-flow diagram were rewritten to include login, merchant selection and the session check.

v2.3.0 — 2026-06-25 — Test Connection validates gateway config#

Type: Behavior change + error-code change
Affects: POST /device/test-connection response and error codes

What changed#

POST /device/test-connection previously validated device-level credentials and pinged the
processor with a hardcoded health URL. It now validates the merchant payment gateway
configuration the device will actually use at payment time — an ACTIVE gateway of the device's
type, with complete credentials accepted by the gateway adapter (plus a VAR sheet for TSYS).
Config validation only — no processor call, no money moved.

Response — additive fields#

{ "status": "ACTIVE", "gatewayType": "TsysSierra", "configStatus": "VALID", "processorStatus": "CONNECTED" }

• gatewayType (new), configStatus: "VALID" (new). processorStatus retained for backward compatibility.

Error codes — changed#

Required app changes#

☐ Read gatewayType / configStatus from the success response (optional; additive)
☐ Handle 422 GATEWAY_NOT_CONFIGURED as NON-retryable — show reason + "contact administrator"
   (admin must fix the gateway config / VAR sheet / credentials in the portal)
☐ Handle 400 GATEWAY_NOT_SUPPORTED
☐ Treat a 200 alreadyActive response as success (stop expecting 422 DEVICE_ALREADY_ACTIVE)
☐ Keep retry only for 503 PROCESSOR_UNREACHABLE

NearPay devices are validated locally (Terminal ID present + NearPay JWT mintable); see Test Connection and Payment Flow by Device Type.

v2.2.0 — 2026-06-16 — Device Config Redesign#

Type: ⚠️ Breaking (fields removed) + Additive (new fields)
Affects: POST /device/register response, GET /device/me response

Impact Assessment#

⚠️ Breaking: 4 fields removed from device responses#

The following columns were dropped from the database. They no longer appear in POST /device/register or GET /device/me responses:

Required app changes:

// Remove these from Device model/struct:
paymentMethod  ← absent from response
routingType    ← absent from response
processorId    ← absent from response
bin            ← absent from response

New: paymentAdjustmentType, paymentAdjustmentValue, paymentAdjustmentCardValue and paymentAdjustmentAchValue#

{
  "paymentAdjustmentType": "FLAT",
  "paymentAdjustmentValue": "1.5000",
  "paymentAdjustmentCardValue": "2.0000",
  "paymentAdjustmentAchValue": "0.5000"
}

Pricing Model Specifics:#

• flat pricing model (or no pricing model configured): Use paymentAdjustmentValue for single adjustment display.
• cashdiscount pricing model: Use paymentAdjustmentCardValue for credit card calculations and paymentAdjustmentAchValue for ACH payment calculations.

Display only — do not apply to the transaction amount. The server computes the final adjusted amount.

New: autoSettleEnabled and settleAt#

{ "autoSettleEnabled": true, "settleAt": "17:00" }

Informational only. Settlement runs server-side; no mobile app action required.

New: jwtNearpayDevice (register) and nearpayJWT (me)#

When paymentMode = "NEARPAY", responses include a signed RS256 JWT for the NearPay SDK.

⚠️ Key name differs by endpoint: POST /device/register → data.jwtNearpayDevice | GET /device/me → data.nearpayJWT

Store alongside deviceToken and pass to the NearPay SDK with nearpayTid.

New: nearpayTid, sunmiSN, iposTpn, iposTpnCode#

New enum values#

No-impact: deviceType portal labels corrected#

The portal previously showed "Countertop" / "Mobile Terminal". Corrected to "Card Reader" / "POS Terminal" to match API enum values. The API values CARD_READER and POS_TERMINAL were always correct — no mobile app changes needed.

Migration checklist for mobile developers#

Breaking — must fix:
  ☐ Remove paymentMethod from Device model/struct
  ☐ Remove routingType from Device model/struct
  ☐ Remove processorId from Device model/struct
  ☐ Remove bin from Device model/struct

New fields — add to Device model/struct:
  ☐ paymentAdjustmentType: String    ("NONE" | "FLAT" | "PERCENTAGE")
  ☐ paymentAdjustmentValue: String?  (decimal string, e.g. "1.5000")
  ☐ paymentAdjustmentCardValue: String? (decimal string, e.g. "2.0000")
  ☐ paymentAdjustmentAchValue: String?  (decimal string, e.g. "0.5000")
  ☐ autoSettleEnabled: Boolean
  ☐ settleAt: String?                ("HH:MM" format)
  ☐ nearpayTid: String?
  ☐ sunmiSN: String?
  ☐ iposTpn: String?
  ☐ iposTpnCode: String?

New enum values:
  ☐ Add SUNMI to manufacturer enum
  ☐ Add NEARPAY to paymentMode enum

Logic:
  ☐ Apply paymentAdjustmentType/Value/CardValue/AchValue in price display before confirmation
  ☐ Pass jwtNearpayDevice (register) or nearpayJWT (me) + nearpayTid to NearPay SDK
  ☐ SUNMI + CARD_READER → no CVV input
  ☐ NEARPAY → no CVV input

v2.0.0 — 2026-06-02 — Device Activation Flow (Phase 1)#

Type: Breaking change
Affects: Registration flow, device status handling, app navigation after register

⚠️ Breaking: POST /device/register no longer activates the device#

Before:

POST /device/register  →  device.status = "ACTIVE"  →  app goes to dashboard

After:

POST /device/register  →  device.status = "REGISTERED"  →  app must call test-connection
POST /device/test-connection (pass)  →  device.status = "ACTIVE"  →  app goes to dashboard

Required app changes:

1. After /register succeeds, check data.testConnectionRequired === true
2. Navigate to a new Test Connection screen instead of the dashboard
3. Call POST /device/test-connection — show loading state
4. On success (status = "ACTIVE") → navigate to dashboard
5. On failure → show error + Retry button

GET /device/me
  └─ status == "REGISTERED"  →  navigate to Test Connection screen  ← NEW case
  └─ status == "ACTIVE"      →  proceed to dashboard (unchanged)
  └─ status == "SUSPENDED"   →  show suspended screen (unchanged)

New: POST /device/test-connection endpoint#

New error codes to handle:

New: DEVICE_NOT_ACTIVE error on device endpoints#

Routes /me, /parameters, /heartbeat, /logout now return 403 DEVICE_NOT_ACTIVE if device is REGISTERED (not yet activated).

Handle this in your startup and heartbeat loops:

403 DEVICE_NOT_ACTIVE  →  navigate to Test Connection screen

Register response — new fields#

POST /device/register response now includes additional fields to guide the app:

{
  "success": true,
  "data": {
    "device": { "status": "REGISTERED", ... },
    "deviceToken": "...",
    "nextStep": "test-connection",
    "testConnectionRequired": true
  }
}

Migration checklist for mobile developers#

• Handle status = "REGISTERED" in /device/me response (startup check)
• Add Test Connection screen (UI + API call)
• Call POST /device/test-connection after each POST /device/register
• Handle testConnectionRequired: true in register response
• Handle 403 DEVICE_NOT_ACTIVE on /device/me, heartbeat and parameters (payment APIs do not re-check ACTIVE)
• Handle new error codes: DEVICE_NOT_REGISTERED, DEVICE_ALREADY_ACTIVE, PROCESSOR_UNREACHABLE, RATE_LIMITED
• Show Retry button for retryable: true errors on test-connection
• Display requestId on error screens for support reference

v1.x.x — Prior to 2026-06-02#

Initial device registration flow. POST /device/register activated the device immediately upon successful TPN + pairing code validation (status = "ACTIVE").