Enroll a device

A phone or terminal can’t take payments until it’s enrolled on your account. Your backend creates a single-use enrollment code, a clerk types it into the Kustom POS app, and the app pairs itself. Creating the code is the only part you build.

Play the sequence

Store clerkKustom POS appKustomYour server

1. 1Create an enrollment
   Your server → Kustom

   POST

   /ipp/v1/enrollmentsauthenticated with your API credentials

   Kustom → Your serverenrollment_code and expires_at
2. 2Hand the code to the clerk
   Your server → Store clerkthe enrollment codeby any route you choose, or your MDM pushes it to the device

   Store clerk → Kustom POS apptypes the code
3. 3The app registers the device
   Kustom POS app → Kustomregister the deviceno API credentials: the code is the credential

   Kustom → Kustom POS appdevice record and bearer token
4. 4Manage the device
   Your server → Kustom

   GET

   /ipp/v1/devices

   Kustom → Your serverdevice_id and your enrollment metadata

Before you start

• In-person payments is enabled on your account.
• The Kustom POS app is installed on the device.
• If your account has more than one location, you know which one the device belongs to. You can list your locations to find the location_id.

Enrolling many managed devices at once? Enroll a managed fleet pushes the codes through your MDM instead.

Step by step

1. Create an enrollment

POST /ipp/v1/enrollments. The response carries an enrollment_code and an expires_at.

The ttl you send decides what kind of code you get:

ttl	Code
TWO_HOURS	A short 8-character code, made for a clerk to type
TWENTY_FOUR_HOURS, FORTY_EIGHT_HOURS, SEVENTY_TWO_HOURS, THIRTY_DAYS	A UUID, made for pushing to a device rather than typing

On an account with more than one location, location_id is required, and it binds the device to that location for good. Sessions don’t carry a location — they inherit the device’s.

Any metadata you attach is carried onto the device record when pairing completes. Tag each enrollment with its store or lane, and you can filter devices by it later.

2. Hand the code to the clerk

How it reaches them is yours to choose. The clerk types it into the Kustom POS app, which registers the device against your account and receives its own bearer token. Nothing more is needed from your backend.

3. Manage the device afterwards

The enrolled device has a stable device_id, which is what you send when you create a session. From here you can list, update and deregister devices.

Name each device when you update it. Nothing in the API says whether a device is a phone or a Kustom terminal, so a name such as “Terminal, till 2” is how you tell them apart in the device list.

Deregistering revokes the device’s bearer token immediately. The clerk has to enroll it again before it can take another payment.

Check that it works

The device appears in GET /ipp/v1/devices, carrying the metadata you set on its enrollment. The enrollment itself has moved to CONSUMED:

Status	Meaning
PENDING	Created, and no clerk has entered it yet
CONSUMED	A device registered with it
EXPIRED	Not used before expires_at. Create a new enrollment
CANCELLED	Deleted with DELETE /ipp/v1/enrollments/{enrollment_id}

CANCELLED and EXPIRED enrollments are left out of list results.

Troubleshooting

The /ipp/v1 endpoints return 404 or 403. In-person payments isn’t enabled on the account. That’s a conversation with your Kustom representative, not a code fix.

The clerk’s code is rejected. It expired or was already used — codes are single-use. Create a new enrollment.

The device needs to move to another location. A device stays bound to the location it enrolled into. Deregister it and enroll it again with the new location_id.

Related

• Take a payment — send a cart to the device you just enrolled
• Test without hardware — a simulated device for Playground
• Enroll a managed fleet — the same enrollment, pushed through your MDM