Skip to content
In-Person Payments
/
/
List devices

In-Person Payments API (1.0.0)

API for accepting in-store payments through Kustom. Your backend creates payment sessions dispatched to registered devices, and the Kustom POS app handles collection. In-Person Payments supports card payments (tap-to-pay) as well as alternative payment methods — Klarna, Swish, and Vipps — collected via Scan to pay. Kustom delivers lifecycle callbacks back to your system.

A device is your own smartphone (iPhone or Android) running the Kustom POS app, installed from the App Store or Google Play. Each device is paired to your account using an enrollment code.

Download OpenAPI description
in-person-payments.json
in-person-payments.yaml
Languages
Servers
Production
https://api.kustom.co
Playground
https://api.playground.kustom.co

Testing

Testing utilities for simulating devices and card taps. Available on playground only — not in production.

Operations

Enrollments

Device enrollment code management for pairing new devices.

Operations

Locations

Manage physical locations associated with a merchant.

Operations

Devices

Device registration and management.

Operations

Update device

Request

Updates device properties such as name, metadata, or location assignment.

Path
idstring(uuid)required

Device ID

Bodyapplication/jsonrequired
namestring

Display name of the device.

Example: "POS Terminal 1"
metadataobject

Custom metadata key-value pairs for the device.

Example: {"store_id":"123","region":"EU"}
location_idstring(uuid)

Location identifier to assign the device to.

Example: "550e8400-e29b-41d4-a716-446655440000"
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"
  }'

Responses

Device updated successfully.

Bodyapplication/json
idstring

Unique device identifier.

Example: "550e8400-e29b-41d4-a716-446655440000"
hardware_idstring

Hardware identifier of the device.

Example: "ABC123XYZ"
merchant_idstring

Merchant identifier.

Example: "merchant_12345"
location_idstring

Location identifier where the device is registered.

Example: "550e8400-e29b-41d4-a716-446655440000"
namestring

Display name of the device.

Example: "POS Terminal 1"
platformstring

Device platform.

Enum"IOS""ANDROID""TERMINAL"
Example: "IOS"
metadataobject

Custom metadata key-value pairs for the device.

Example: {"store_id":"123","region":"EU"}
created_atstring(date-time)

Timestamp when the device was created.

Example: "2024-01-15T10:30:00Z"
open_cash_register_idinteger(int32)

ID of the currently open cash register on this device.

Example: 42
credentialsobject(DeviceCredentialsPublicResponse)

Device credentials (only returned during registration).

unique_idstringDeprecated

Hardware identifier (deprecated, use hardwareId).

Example: "ABC123XYZ"
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 device

Request

Removes a device from the merchant's account. The device will no longer be able to process payments.

Path
idstring(uuid)required

Device ID

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

Responses

Device deregistered successfully.

Response
No content

List devices

Request

Lists all registered devices for the merchant, optionally filtered by location.

Query
location_idstring(uuid)

Filter by location ID.

metadataArray of strings

Filter by metadata key-value pair. Format: key:value. Repeat the parameter to apply multiple filters — all must match (AND semantics). Maximum 5 entries. Duplicate keys are not allowed.

Example: metadata=store_id:123
page_numberinteger(int32)>= 0

Zero-based page number. Defaults to 0.

Default 0
page_sizeinteger(int32)> 0

Page size. Defaults to 20.

Default 20
Headers
x-merchant-idstringnon-emptyrequired
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'

Responses

List of devices.

Bodyapplication/json
contentArray of any
total_elementsinteger(int64)
total_pagesinteger(int32)
page_numberinteger(int32)
page_sizeinteger(int32)
firstboolean
lastboolean
Response
application/json
{
  "content": [
    { … },
    { … }
  ],
  "total_elements": 2,
  "total_pages": 1,
  "page_number": 0,
  "page_size": 20,
  "first": true,
  "last": true
}

Sessions

Session lifecycle management.

Operations