Skip to content
In-Person Payments
/
/
Cancel session

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

Sessions

Session lifecycle management.

Operations

Cancel session

Request

Cancels a session. Triggers a session.cancelled callback. This is a terminal state — no further payment collection is possible.

Path
session_idstring(uuid)required
curl -i -X PUT \
  'https://api.kustom.co/ipp/v1/sessions/{session_id}/cancel'

Responses

Session cancelled.

Bodyapplication/json
session_idstring(uuid)

Unique session identifier.

Example: "550e8400-e29b-41d4-a716-446655440000"
statusstring(SessionStatusDto)

Current session status.

Enum"CREATED""ACTIVE""FINALIZED""CANCELLED""EXPIRED""FAILED"
device_idstring(uuid)

Device ID handling the session.

Example: "660e8400-e29b-41d4-a716-446655440001"
order_idstring

Order ID once created.

Example: "770e8400-e29b-41d4-a716-446655440002"
order_amountinteger(int64)

Total order amount in minor units.

Example: 2000
purchase_currencystring

Currency code (ISO 4217).

Example: "SEK"
purchase_started_atstring(date-time)

Timestamp when the purchase started.

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

Timestamp when the purchase was completed.

Example: "2024-01-15T10:35:00Z"
order_itemsArray of objects(LineItemDto)

List of line items in the order.

merchant_reference1string

First merchant reference.

Example: "ORDER-12345"
merchant_reference2string

Second merchant reference.

Example: "REF-67890"
order_tax_amountinteger(int32)

Total tax amount in minor units.

Example: 400
merchant_datastring

Arbitrary merchant data.

Example: {"customer_id":"C123"}
created_atstring(date-time)

Timestamp when the session was created.

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

Timestamp when the session expires.

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

Timestamp when the session was last updated.

Example: "2024-01-15T10:35:00Z"
Response
application/json
{
  "session_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "CANCELLED",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "order_amount": 240000,
  "purchase_currency": "SEK",
  "purchase_started_at": "2024-01-15T10:30:00Z",
  "order_tax_amount": 48000,
  "merchant_reference1": "ORDER-12345",
  "order_items": [
    { … }
  ]
}

Create session

Request

Creates a session to be collected by an In-Person Payment device. Dispatches it to the target device. Lifecycle callbacks are delivered to the URL configured in the merchant portal.

Query
location_idstring(uuid)

Location ID - Mandatory if merchant has multiple locations

Bodyapplication/jsonrequired
device_idstring(uuid)required

Target device ID.

Example: "550e8400-e29b-41d4-a716-446655440000"
order_amountinteger(int64)required

Total order amount in minor units (e.g., cents).

Example: 2000
purchase_currencystring= 3 charactersrequired

Currency code (ISO 4217).

Example: "SEK"
purchase_started_atstring(date-time)required

Timestamp when the purchase started.

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

Timestamp when the purchase was completed.

Example: "2024-01-15T10:35:00Z"
order_itemsArray of objects(LineItemDto)non-emptyrequired

List of line items in the order.

merchant_reference1string

First merchant reference for tracking purposes.

Example: "ORDER-12345"
merchant_reference2string

Second merchant reference for tracking purposes.

Example: "REF-67890"
order_tax_amountinteger(int32)required

Total tax amount for the order in minor units.

Example: 400
merchant_datastring

Arbitrary merchant data (JSON string).

Example: {"customer_id":"C123"}
curl -i -X POST \
  'https://api.kustom.co/ipp/v1/sessions?location_id=497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Content-Type: application/json' \
  -d '{
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "order_amount": 240000,
    "purchase_currency": "SEK",
    "purchase_started_at": "2024-01-15T10:30:00Z",
    "order_tax_amount": 48000,
    "merchant_reference1": "ORDER-12345",
    "order_items": [
      {
        "type": "physical",
        "reference": "SKU-001",
        "name": "T-Shirt",
        "quantity": 2,
        "unit_price": 100000,
        "total_amount": 200000,
        "tax_rate": 2500,
        "total_tax_amount": 40000
      },
      {
        "type": "physical",
        "reference": "SKU-002",
        "name": "Socks",
        "quantity": 1,
        "unit_price": 40000,
        "total_amount": 40000,
        "tax_rate": 2500,
        "total_tax_amount": 8000
      }
    ]
  }'

Responses

Session created and dispatched to device.

Bodyapplication/json
session_idstring(uuid)

Unique session identifier.

Example: "550e8400-e29b-41d4-a716-446655440000"
statusstring(SessionStatusDto)

Current session status.

Enum"CREATED""ACTIVE""FINALIZED""CANCELLED""EXPIRED""FAILED"
device_idstring(uuid)

Device ID handling the session.

Example: "660e8400-e29b-41d4-a716-446655440001"
order_idstring

Order ID once created.

Example: "770e8400-e29b-41d4-a716-446655440002"
order_amountinteger(int64)

Total order amount in minor units.

Example: 2000
purchase_currencystring

Currency code (ISO 4217).

Example: "SEK"
purchase_started_atstring(date-time)

Timestamp when the purchase started.

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

Timestamp when the purchase was completed.

Example: "2024-01-15T10:35:00Z"
order_itemsArray of objects(LineItemDto)

List of line items in the order.

merchant_reference1string

First merchant reference.

Example: "ORDER-12345"
merchant_reference2string

Second merchant reference.

Example: "REF-67890"
order_tax_amountinteger(int32)

Total tax amount in minor units.

Example: 400
merchant_datastring

Arbitrary merchant data.

Example: {"customer_id":"C123"}
created_atstring(date-time)

Timestamp when the session was created.

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

Timestamp when the session expires.

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

Timestamp when the session was last updated.

Example: "2024-01-15T10:35:00Z"
Response
application/json
{
  "session_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "CREATED",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "order_amount": 240000,
  "purchase_currency": "SEK",
  "purchase_started_at": "2024-01-15T10:30:00Z",
  "order_tax_amount": 48000,
  "merchant_reference1": "ORDER-12345",
  "order_items": [
    { … },
    { … }
  ]
}

Get session

Request

Retrieves session details by ID.

Path
session_idstring(uuid)required
curl -i -X GET \
  'https://api.kustom.co/ipp/v1/sessions/{session_id}'

Responses

Session details.

Bodyapplication/json
session_idstring(uuid)

Unique session identifier.

Example: "550e8400-e29b-41d4-a716-446655440000"
statusstring(SessionStatusDto)

Current session status.

Enum"CREATED""ACTIVE""FINALIZED""CANCELLED""EXPIRED""FAILED"
device_idstring(uuid)

Device ID handling the session.

Example: "660e8400-e29b-41d4-a716-446655440001"
order_idstring

Order ID once created.

Example: "770e8400-e29b-41d4-a716-446655440002"
order_amountinteger(int64)

Total order amount in minor units.

Example: 2000
purchase_currencystring

Currency code (ISO 4217).

Example: "SEK"
purchase_started_atstring(date-time)

Timestamp when the purchase started.

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

Timestamp when the purchase was completed.

Example: "2024-01-15T10:35:00Z"
order_itemsArray of objects(LineItemDto)

List of line items in the order.

merchant_reference1string

First merchant reference.

Example: "ORDER-12345"
merchant_reference2string

Second merchant reference.

Example: "REF-67890"
order_tax_amountinteger(int32)

Total tax amount in minor units.

Example: 400
merchant_datastring

Arbitrary merchant data.

Example: {"customer_id":"C123"}
created_atstring(date-time)

Timestamp when the session was created.

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

Timestamp when the session expires.

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

Timestamp when the session was last updated.

Example: "2024-01-15T10:35:00Z"
Response
application/json
{
  "session_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "ACTIVE",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": "770e8400-e29b-41d4-a716-446655440002",
  "order_amount": 240000,
  "purchase_currency": "SEK",
  "purchase_started_at": "2024-01-15T10:30:00Z",
  "order_tax_amount": 48000,
  "merchant_reference1": "ORDER-12345",
  "order_items": [
    { … }
  ]
}