# In-Person Payments API

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.

Version: 1.0.0

## Servers

Production
```
https://api.kustom.co
```

Playground
```
https://api.playground.kustom.co
```

## Download OpenAPI description

[In-Person Payments API](https://docs.kustom.co/_bundle/contents/api/in-person-payments.yaml)

## Testing

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

### Simulate card tap

 - [POST /ipp/v1/dev/sessions/{sessionId}/simulate-tap](https://docs.kustom.co/contents/api/in-person-payments/testing/simulatecardtap.md): 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.

### Create simulated device

 - [POST /ipp/v1/dev/devices](https://docs.kustom.co/contents/api/in-person-payments/testing/createsimulateddevice.md): 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.

## Enrollments

Device enrollment code management for pairing new devices.

### List enrollments

 - [GET /ipp/v1/enrollments](https://docs.kustom.co/contents/api/in-person-payments/enrollments/listenrollments.md): 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.

### Create enrollment

 - [POST /ipp/v1/enrollments](https://docs.kustom.co/contents/api/in-person-payments/enrollments/createenrollment.md): Creates a new enrollment code that a device can use to register.

### Delete enrollment

 - [DELETE /ipp/v1/enrollments/{enrollment_id}](https://docs.kustom.co/contents/api/in-person-payments/enrollments/deleteenrollments.md): Soft-deletes an enrollment. The enrollment will no longer appear in list results.

## Locations

Manage physical locations associated with a merchant.

### List locations

 - [GET /ipp/v1/locations](https://docs.kustom.co/contents/api/in-person-payments/locations/listlocations.md): Returns a paginated list of locations belonging to the authenticated merchant.

### Get location

 - [GET /ipp/v1/locations/{id}](https://docs.kustom.co/contents/api/in-person-payments/locations/getlocation.md): Returns a single location by ID, scoped to the authenticated merchant.

## Devices

Device registration and management.

### Update device

 - [PUT /ipp/v1/devices/{id}](https://docs.kustom.co/contents/api/in-person-payments/devices/updatedevice.md): Updates device properties such as name, metadata, or location assignment.

### Deregister device

 - [DELETE /ipp/v1/devices/{id}](https://docs.kustom.co/contents/api/in-person-payments/devices/deregisterdevice.md): Removes a device from the merchant's account. The device will no longer be able to process payments.

### List devices

 - [GET /ipp/v1/devices](https://docs.kustom.co/contents/api/in-person-payments/devices/listdevices.md): Lists all registered devices for the merchant, optionally filtered by location.

## Sessions

Session lifecycle management.

### Cancel session

 - [PUT /ipp/v1/sessions/{session_id}/cancel](https://docs.kustom.co/contents/api/in-person-payments/sessions/cancelsession.md): Cancels a session. Triggers a session.cancelled callback. This is a terminal state — no further payment collection is possible.

### Create session

 - [POST /ipp/v1/sessions](https://docs.kustom.co/contents/api/in-person-payments/sessions/createsession.md): 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.

### Get session

 - [GET /ipp/v1/sessions/{session_id}](https://docs.kustom.co/contents/api/in-person-payments/sessions/getsession.md): Retrieves session details by ID.