Skip to content
/
Enroll a Device
Last updated

Enroll a Device

Before a device can receive payment sessions, it must be enrolled on your merchant account. Your backend (or the Kustom Portal) generates a pairing code that a store clerk enters in the Kustom POS app. This registers the device automatically and receives an authentication token.

Participants

ParticipantRole
Merchant OpsMerchant internal team with access to the Kustom Portal — or a third-party system connected to the Kustom Device API. Creates enrollments and controls which devices are assigned to specific locations.
Store ClerkMerchant employee using the Kustom POS app to collect in-person payments; enters the pairing code in the app.
Kustom POSKustom POS app for iOS or Android running on any certified device.
Device APIKustom device API, used to manage the device fleet.

How enrollment works

The first step (creating the enrollment) is the only part you implement, and it uses your API key. Registering the device is handled internally by the Kustom POS app once the clerk enters the pairing code.

Device APIKustom POSDevice APIKustom POSMerchant operations create enrollment via portal or API.The enrollment has an expiration date and metadata (key-value)that will be carried over to the device record once pairing code is linked to the deviceand could be used to query devices.critical[Authentication using API keys]Merchants decide how to distribute the pairing code.Use pairing code to register deviceand connect it to merchantCredentials returned at this point willbe used for further API requests from Kustom POScritical[No authentication]Merchant OpsShopperStore ClerkCreate enrollmentReturn pairing codeSends pairing codeEnter pairing codeRegister deviceReturn device record and auth credentialsMerchant OpsShopperStore Clerk

Create an enrollment

Generates a short-lived pairing code. The metadata you provide in the enrollment is carried over to the device record once paired, and can be used later to filter devices.

Generate an enrollment code

curl -i -X POST \
  https://api.kustom.co/ipp/v1/enrollments \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "username": "john.doe",
      "type": "android"
    },
    "expires_in": 36000,
    "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795"
  }'
Response
application/json
{
  "enrollment_id": "660e8400-e29b-41d4-a716-446655440001",
  "enrollment_code": "ABC123XYZ",
  "expires_at": "2024-01-15T11:30:00Z",
  "status": "PENDING",
  "metadata": {
    "store_id": "123",
    "terminal_type": "checkout"
  }
}

Share the enrollment_code with the store clerk, and they will enter it in the Kustom POS app. The app then calls the device registration endpoint (unauthenticated) and receives a device bearer token. This is handled entirely by the app; no further action is needed from your backend.

Enrollment status

StatusMeaning
PENDINGCode generated, not yet entered by a clerk.
CONSUMEDDevice successfully registered.
EXPIREDCode not used before expires_at. Please generate a new enrollment.
CANCELLEDManually deleted via DELETE /ipp/v1/enrollments/{id}.

CANCELLED and EXPIRED enrollments are excluded from the list results. If the code expires before the clerk enters it, create a new enrollment.

Manage registered devices

Once enrolled, a device has a stable device_id, which you use when creating sessions. The device metadata (carried over from the enrollment) can be used to filter devices in list queries.

List devices

curl -i -X GET \
  'https://api.kustom.co/ipp/v1/devices?location_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&metadata=store_id%3A123&page_number=0&page_size=20' \
  -H 'x-merchant-id: string'
Response
application/json
{
  "content": [
    { … },
    { … }
  ],
  "total_elements": 2,
  "total_pages": 1,
  "page_number": 0,
  "page_size": 20,
  "first": true,
  "last": true
}

Update device

curl -i -X PUT \
  'https://api.kustom.co/ipp/v1/devices/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "POS Terminal - Main Entrance",
    "metadata": {
      "store_id": "456",
      "department": "Sales"
    },
    "location_id": "660e8400-e29b-41d4-a716-446655440001"
  }'
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "hardware_id": "ABC123XYZ",
  "merchant_id": "merchant_12345",
  "location_id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "POS Terminal - Main Entrance",
  "platform": "IOS",
  "metadata": {
    "store_id": "456",
    "department": "Sales"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Deregister a device

curl -i -X DELETE \
  'https://api.kustom.co/ipp/v1/devices/{id}'
Response
No content

Deregistering a device revokes its bearer token immediately. The clerk will need to re-enroll if the device is to be used again.

Previous page
Next page