POST

Create session

https://api.kustom.co/ipp/v1/sessions

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.

Request body19 fields

device_idstring · uuidrequired
Target device ID.
order_amountinteger · int64required
Total order amount in minor units (e.g., cents).
purchase_currencystringrequired
Currency code (ISO 4217).
purchase_started_atstring · date-timerequired
Timestamp when the purchase started.
purchase_completed_atstring · date-timeoptional
Timestamp when the purchase was completed.
order_items[]array<object>required
List of line items in the order.
9 fields in order_items
- typestringrequired
  Type of the line item.
  - physical
  - discount
  - shipping_fee
  - sales_tax
  - store_credit
  - gift_card
  - digital
  - surcharge
  - return_fee
  - package
- referencestringoptional
  External reference ID for the item (e.g., SKU).
- namestringrequired
  Name or description of the item.
- quantityinteger · int64required
  Quantity of the item.
- unit_priceinteger · int64required
  Unit price in minor units (e.g., cents).
- total_amountinteger · int64required
  Total amount for this line in minor units.
- tax_rateinteger · int32required
  Tax rate in basis points (e.g., 2500 for 25%).
- total_discount_amountinteger · int64optional
  Total discount amount in minor units.
- total_tax_amountinteger · int64required
  Total tax amount for this line in minor units.
merchant_reference1stringoptional
First merchant reference for tracking purposes.
merchant_reference2stringoptional
Second merchant reference for tracking purposes.
order_tax_amountinteger · int32required
Total tax amount for the order in minor units.
merchant_datastringoptional
Arbitrary merchant data (JSON string).

200

Response25 fields

Session created and dispatched to device.

session_idstring · uuidoptional
Unique session identifier.
statusstringoptional
Current session status.
- CREATED
- ACTIVE
- FINALIZED
- CANCELLED
- EXPIRED
- FAILED
device_idstring · uuidoptional
Device ID handling the session.
order_idstringoptional
Order ID once created.
order_amountinteger · int64optional
Total order amount in minor units.
purchase_currencystringoptional
Currency code (ISO 4217).
purchase_started_atstring · date-timeoptional
Timestamp when the purchase started.
purchase_completed_atstring · date-timeoptional
Timestamp when the purchase was completed.
order_items[]array<object>optional
List of line items in the order.
9 fields in order_items
- typestringrequired
  Type of the line item.
  - physical
  - discount
  - shipping_fee
  - sales_tax
  - store_credit
  - gift_card
  - digital
  - surcharge
  - return_fee
  - package
- referencestringoptional
  External reference ID for the item (e.g., SKU).
- namestringrequired
  Name or description of the item.
- quantityinteger · int64required
  Quantity of the item.
- unit_priceinteger · int64required
  Unit price in minor units (e.g., cents).
- total_amountinteger · int64required
  Total amount for this line in minor units.
- tax_rateinteger · int32required
  Tax rate in basis points (e.g., 2500 for 25%).
- total_discount_amountinteger · int64optional
  Total discount amount in minor units.
- total_tax_amountinteger · int64required
  Total tax amount for this line in minor units.
merchant_reference1stringoptional
First merchant reference.
merchant_reference2stringoptional
Second merchant reference.
order_tax_amountinteger · int32optional
Total tax amount in minor units.
merchant_datastringoptional
Arbitrary merchant data.
created_atstring · date-timeoptional
Timestamp when the session was created.
expires_atstring · date-timeoptional
Timestamp when the session expires.
updated_atstring · date-timeoptional
Timestamp when the session was last updated.

400

Response0 fields

Invalid request body or parameters.

No response body — this status returns headers only.

401

Response0 fields

Missing or invalid credentials.

No response body — this status returns headers only.

404

Response0 fields

Target device not found or inactive.

No response body — this status returns headers only.

POST https://api.kustom.co/ipp/v1/sessions

Request body· application/json

{
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "order_amount": 2000,
  "purchase_currency": "SEK",
  "purchase_started_at": "2024-01-15T10:30:00Z",
  "purchase_completed_at": "2024-01-15T10:35:00Z",
  "order_items": [
    {
      "type": "physical",
      "reference": "SKU-12345",
      "name": "T-Shirt",
      "quantity": 2,
      "unit_price": 1000,
      "total_amount": 2000,
      "tax_rate": 2500,
      "total_discount_amount": 200,
      "total_tax_amount": 400
    }
  ],
  "merchant_reference1": "ORDER-12345",
  "merchant_reference2": "REF-67890",
  "order_tax_amount": 400,
  "merchant_data": {
    "customer_id": "C123"
  }
}

26 lines

Response 200· Session created and dispatched to device.

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CREATED",
  "device_id": "660e8400-e29b-41d4-a716-446655440001",
  "order_id": "770e8400-e29b-41d4-a716-446655440002",
  "order_amount": 2000,
  "purchase_currency": "SEK",
  "purchase_started_at": "2024-01-15T10:30:00Z",
  "purchase_completed_at": "2024-01-15T10:35:00Z",
  "order_items": [
    {
      "type": "physical",
      "reference": "SKU-12345",
      "name": "T-Shirt",
      "quantity": 2,
      "unit_price": 1000,
      "total_amount": 2000,
      "tax_rate": 2500,
      "total_discount_amount": 200,
      "total_tax_amount": 400
    }
  ],
  "merchant_reference1": "ORDER-12345",
  "merchant_reference2": "REF-67890",
  "order_tax_amount": 400,
  "merchant_data": {
    "customer_id": "C123"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-15T11:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

32 lines

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.