Skip to content
/Testing

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

Simulate card tap

Request

Simulates a physical card tap on the terminal reader, bypassing the need for real hardware. Uses Stripe test helpers to simulate a card-present payment with the requested outcome. Only available in non-production environments.

Path
sessionIdstring(uuid)required
Query
outcomestring
Default "SUCCESS"
Enum"SUCCESS""DECLINED_GENERIC""INSUFFICIENT_FUNDS""LOST_CARD""STOLEN_CARD""EXPIRED_CARD""INCORRECT_CVC""PROCESSING_ERROR""INCORRECT_NUMBER""CARD_VELOCITY_EXCEEDED"
curl -i -X POST \
  'https://api.kustom.co/ipp/v1/dev/sessions/{sessionId}/simulate-tap?outcome=SUCCESS'

Responses

Card tap simulated successfully.

Create simulated device

Request

Creates a simulated device by generating an enrollment and immediately registering it. Always adds simulated=true to the device metadata. Only available in non-production environments.

Bodyapplication/jsonrequired
namestringnon-emptyrequired
location_idstring(uuid)
metadataobject
curl -i -X POST \
  https://api.kustom.co/ipp/v1/dev/devices \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
    "metadata": {
      "property1": "string",
      "property2": "string"
    }
  }'

Responses

Simulated device created.

Body*/*
device_idstring(uuid)

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