Skip to content
/Enrollments

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

List enrollments

Request

Returns a paginated list of enrollments for the merchant. Soft-deleted (CANCELLED) enrollments are always excluded. Results can be filtered by location, by metadata key-value pairs, and by whether consumed enrollments are included.

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
include_consumedboolean

Whether to include CONSUMED enrollments. Defaults to true.

Default true
page_numberinteger(int32)>= 0

Zero-based page number. Defaults to 0.

Default 0
page_sizeinteger(int32)[ 1 .. 100 ]

Page size. Defaults to 20.

Default 20
Headers
x-merchant-idstringnon-emptyrequired
curl -i -X GET \
  'https://api.kustom.co/ipp/v1/enrollments?location_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&metadata=store_id%3A123&include_consumed=true&page_number=0&page_size=20' \
  -H 'x-merchant-id: string'

Responses

Paginated list of enrollments.

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
}

Create enrollment

Request

Creates a new enrollment code that a device can use to register.

Bodyapplication/jsonrequired
metadataobject

Custom metadata key-value pairs for the enrollment.

Example: {"store_id":"123","terminal_type":"checkout"}
expires_ininteger(int64)

Time in milliseconds until the enrollment code expires. Defaults to 7200000 (2 hours).

Example: 360000
location_idstring(uuid)

Location ID to associate the enrolled device with.

Example: "550e8400-e29b-41d4-a716-446655440000"
curl -i -X POST \
  https://api.kustom.co/ipp/v1/enrollments \
  -H 'Content-Type: application/json' \
  -d '{
    "location_id": "550e8400-e29b-41d4-a716-446655440000",
    "expires_in": 360000,
    "metadata": {
      "store_id": "123",
      "terminal_type": "checkout"
    }
  }'

Responses

Enrollment created.

Bodyapplication/json
enrollment_idstring(uuid)

Unique enrollment identifier.

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

The enrollment code to enter on the device.

Example: "ABC123XYZ"
expires_atstring(date-time)

Timestamp when the enrollment code expires.

Example: "2024-01-15T11:30:00Z"
statusstring

Current status of the enrollment.

Enum"PENDING""CONSUMED""EXPIRED""CANCELLED"
metadataobject

Custom metadata key-value pairs for the enrollment.

Example: {"store_id":"123","terminal_type":"checkout"}
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"
  }
}

Delete enrollment

Request

Soft-deletes an enrollment. The enrollment will no longer appear in list results.

Path
enrollment_idstring(uuid)required

Enrollment ID.

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

Responses

Enrollment deleted.

Response
No content

Locations

Manage physical locations associated with a merchant.

Operations

Devices

Device registration and management.

Operations

Sessions

Session lifecycle management.

Operations