Skip to content
/Locations

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

List locations

Request

Returns a paginated list of locations belonging to the authenticated merchant.

Query
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

Merchant ID resolved from the API key.

curl -i -X GET \
  'https://api.kustom.co/ipp/v1/locations?page_number=0&page_size=20' \
  -H 'x-merchant-id: string'

Responses

Locations retrieved successfully.

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
}

Get location

Request

Returns a single location by ID, scoped to the authenticated merchant.

Path
idstring(uuid)required
Headers
x-merchant-idstringnon-emptyrequired

Merchant ID resolved from the API key.

curl -i -X GET \
  'https://api.kustom.co/ipp/v1/locations/{id}' \
  -H 'x-merchant-id: string'

Responses

Location found.

Bodyapplication/json
idstring(uuid)

Unique location identifier.

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

Merchant identifier.

Example: "merchant_12345"
namestring

Display name of the location.

Example: "Downtown Store"
street_addressstring

Primary street address.

Example: 123
street_address2string

Secondary address line (suite, apartment, etc.).

Example: "Suite 100"
postal_codestring

Postal or ZIP code.

Example: 12345
citystring

City name.

Example: "Stockholm"
countrystring

Country code (ISO 3166-1 alpha-2).

Example: "SE"
created_atstring(date-time)

Timestamp when the location was created.

Example: "2024-01-15T10:30:00Z"
updated_atstring(date-time)

Timestamp when the location was last updated.

Example: "2024-01-20T14:45:00Z"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "merchant_12345",
  "name": "Downtown Store",
  "street_address": "123 Main Street",
  "street_address2": "Suite 100",
  "postal_code": "12345",
  "city": "Stockholm",
  "country": "SE",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

Devices

Device registration and management.

Operations

Sessions

Session lifecycle management.

Operations