Skip to content
/
Testing
Last updated

Testing

The playground environment provides two dev-only endpoints, letting you test the full payment flow without a physical terminal.

The Dev endpoints (/ipp/v1/dev/*) are only available in playground (api.playground.kustom.co). Calls to these endpoints in production will result in 404.

Step 1 — Create a simulated device

Creates a simulated device — no Kustom POS app needed. The device is immediately registered and ready to receive sessions.

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"
    }
  }'

Use the returned device_id when creating sessions. The device will have simulated: true in its metadata.

Step 2 — Create a session

Create a session targeting your simulated device, exactly as you would in production:

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
      }
    ]
  }'

Step 3 — Simulate a card tap

Simulates a physical card tap on the terminal, triggering the payment outcome of your choice.

curl -i -X POST \
  'https://api.kustom.co/ipp/v1/dev/sessions/{sessionId}/simulate-tap?outcome=SUCCESS'

Available outcomes

OutcomeWhat happens
SUCCESSPayment approved. Session moves to FINALIZED.
DECLINED_GENERICCard declined (generic reason).
INSUFFICIENT_FUNDSCard declined due to insufficient funds.
LOST_CARDCard reported lost.
STOLEN_CARDCard reported stolen.
EXPIRED_CARDCard has expired.
INCORRECT_CVCWrong CVC entered.
PROCESSING_ERRORTerminal processing error.
INCORRECT_NUMBERInvalid card number.
CARD_VELOCITY_EXCEEDEDCard velocity limit exceeded.

outcome defaults to SUCCESS if omitted.

Testing checklist

Before going live, verify the following against your playground integration:

  • Device enrolled and visible in the device list
  • Session created and dispatched to the device (status CREATED)
  • session.finalized callback received and processed
  • order_id from callback successfully linked to your order record
  • Declined payment (DECLINED_GENERIC) handled gracefully
  • Session cancellation flow tested
  • Callback endpoint returns 2xx reliably
Previous page
Next page