{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-contents/checkout/sidebars.yaml","oas-contents/api/in-person-payments.json":"oas-contents/api/in-person-payments.json"},"props":{"metadata":{"markdoc":{"tagList":["openapi-code-sample","openapi-response-sample","admonition"]},"type":"markdown"},"seo":{"title":"Enroll a Device","description":"Explore our documentation and API and start integrating Kustom Checkout","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"enroll-a-device","__idx":0},"children":["Enroll a Device"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"participants","__idx":1},"children":["Participants"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Participant"},"children":["Participant"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Role"},"children":["Role"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant Ops"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Merchant 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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store Clerk"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Merchant employee using the Kustom POS app to collect in-person payments; enters the pairing code in the app."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Kustom POS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Kustom POS app for iOS or Android running on any certified device."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Device API"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Kustom device API, used to manage the device fleet."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-enrollment-works","__idx":2},"children":["How enrollment works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n\tactor Merchant Ops\n\tactor Shopper\n\tactor Store Clerk\n\tparticipant Kustom POS\n\tparticipant Device API\n\t\n\tcritical Authentication using API keys\n\t\tMerchant Ops->>+Device API: Create enrollment\n\t Note over Merchant Ops,Device API: Merchant 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 device
and could be used to query devices.\n\t Device API->>-Merchant Ops: Return pairing code\n end\n\n critical No authentication\n\t Merchant Ops->>Store Clerk: Sends pairing code\n\t Note over Merchant Ops,Store Clerk: Merchants decide how to distribute the pairing code.\n\t Store Clerk->>Kustom POS: Enter pairing code\n\t\n\t Kustom POS->>+Device API: Register device\n\t\tNote over Kustom POS,Device API: Use pairing code to register device
and connect it to merchant\n\t\tDevice API->>-Kustom POS: Return device record and auth credentials\n\t\tNote over Kustom POS,Device API: Credentials returned at this point will
be used for further API requests from Kustom POS\n\tend\n","diagramHtml":"
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
"},"children":["sequenceDiagram\n\tactor Merchant Ops\n\tactor Shopper\n\tactor Store Clerk\n\tparticipant Kustom POS\n\tparticipant Device API\n\t\n\tcritical Authentication using API keys\n\t\tMerchant Ops->>+Device API: Create enrollment\n\t Note over Merchant Ops,Device API: Merchant 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 device
and could be used to query devices.\n\t Device API->>-Merchant Ops: Return pairing code\n end\n\n critical No authentication\n\t Merchant Ops->>Store Clerk: Sends pairing code\n\t Note over Merchant Ops,Store Clerk: Merchants decide how to distribute the pairing code.\n\t Store Clerk->>Kustom POS: Enter pairing code\n\t\n\t Kustom POS->>+Device API: Register device\n\t\tNote over Kustom POS,Device API: Use pairing code to register device
and connect it to merchant\n\t\tDevice API->>-Kustom POS: Return device record and auth credentials\n\t\tNote over Kustom POS,Device API: Credentials returned at this point will
be used for further API requests from Kustom POS\n\tend\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-an-enrollment","__idx":3},"children":["Create an enrollment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"generate-an-enrollment-code","__idx":4},"children":["Generate an enrollment code"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"createEnrollment","parameters":{},"requestBody":{"metadata":{"username":"john.doe","type":"android"},"expires_in":36000,"location_id":"46910cc3-ab41-4b80-b4a7-94dab9f1b795"},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"OpenApiResponseSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"createEnrollment"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Share the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"enrollment-status","__idx":5},"children":["Enrollment status"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Code generated, not yet entered by a clerk."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONSUMED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Device successfully registered."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXPIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Code not used before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]},". Please generate a new enrollment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Manually deleted via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /ipp/v1/enrollments/{id}"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXPIRED"]}," enrollments are excluded from the list results. If the code expires before the clerk enters it, create a new enrollment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"manage-registered-devices","__idx":6},"children":["Manage registered devices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once enrolled, a device has a stable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"list-devices","__idx":7},"children":["List devices"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"listDevices","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"OpenApiResponseSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"listDevices"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"update-device","__idx":8},"children":["Update device"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"updateDevice","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"OpenApiResponseSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"updateDevice"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"deregister-a-device","__idx":9},"children":["Deregister a device"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"deregisterDevice","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"OpenApiResponseSample","attributes":{"descriptionFile":"oas-contents/api/in-person-payments.json","operationId":"deregisterDevice"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deregistering a device revokes its bearer token immediately. The clerk will need to re-enroll if the device is to be used again."]}]}]},"headings":[{"value":"Enroll a Device","id":"enroll-a-device","depth":1},{"value":"Participants","id":"participants","depth":2},{"value":"How enrollment works","id":"how-enrollment-works","depth":2},{"value":"Create an enrollment","id":"create-an-enrollment","depth":2},{"value":"Generate an enrollment code","id":"generate-an-enrollment-code","depth":4},{"value":"Enrollment status","id":"enrollment-status","depth":3},{"value":"Manage registered devices","id":"manage-registered-devices","depth":2},{"value":"List devices","id":"list-devices","depth":4},{"value":"Update device","id":"update-device","depth":4},{"value":"Deregister a device","id":"deregister-a-device","depth":4}],"frontmatter":{"title":"Enroll a Device","description":"Generate an enrollment code via the API, then have a store clerk enter it in the Kustom POS app. The app registers the device and receives a bearer token for further requests.","seo":{"title":"Enroll a Device"}},"lastModified":"2026-06-10T07:37:02.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/contents/checkout/in-person-payments/enroll-device","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}