cancel`

Endpoint: POST /api/v1/daemonx/onboarding/sessions/:id/cancel
Auth Scope: Developer Token Protected (Writable Token Required)
Target Service: Nyxzie Cloud Core API
Introduced In: v1.0.0
Last Updated: v1.0.0

1. Description & Purpose

POST /api/v1/daemonx/onboarding/sessions/:id/cancel cancels an active or pending onboarding pairing session before it is claimed or completed on a physical workstation.

Use cases:

User Aborted Setup: Cashier or administrator closes the pairing modal or clicks "Cancel" on the POS UI.
Session Cleanup: Invalidate an outstanding 6-digit pairing code before its 900-second TTL expires.
Idempotent Invalidation: Safe to call multiple times; already-cancelled sessions return the current cancelled session representation.

NOTE

Sessions that have already transitioned to "completed" cannot be cancelled and will return a 409 Conflict (DAEMONX_ONBOARDING_COMPLETED). To deactivate an already paired counter, use the counter unpair lifecycle.

2. Request Headers

Header Name	Type	Required	Description	Example
`Authorization`	`string`	Yes	Developer API Bearer Token (must have write permissions)	`Bearer nyx_daemonx_live_6b431eda073e...`
`Content-Type`	`string`	No	Body media type	`application/json`
`Accept`	`string`	No	Response format	`application/json`

3. Path Parameters

Parameter	Type	Required	Description	Example
`id`	`string` (UUID)	Yes	The onboarding session UUID to cancel.	`4b68ff5e-f001-4475-8025-a741544256eb`

4. Request Body

This endpoint is an empty-body command action. No parameters are required.

{}

5. Successful Response Example (200 OK)

{
  "success": true,
  "onboarding_session": {
    "id": "4b68ff5e-f001-4475-8025-a741544256eb",
    "status": "cancelled",
    "external_customer_ref": "cust_milan_01",
    "external_location_ref": "loc_colombo_flagship",
    "external_counter_ref": "pos_lane_01",
    "counter_name": "Cashier Counter 1",
    "environment": "live",
    "is_sandbox": false,
    "counter_id": null,
    "completed_at": null,
    "expires_at": "2026-10-07T02:38:24.000Z",
    "created_at": "2026-10-07T02:33:24.000Z"
  }
}

6. Error Responses

6.1. Cannot Cancel Completed Session (`409 Conflict`)

If the workstation has already completed pairing and bound to the session:

{
  "success": false,
  "error": "Completed DaemonX onboarding sessions cannot be cancelled.",
  "code": "DAEMONX_ONBOARDING_COMPLETED"
}

6.2. Session Not Found (`404 Not Found`)

If the session UUID does not exist or belongs to another developer profile:

{
  "success": false,
  "error": "DaemonX onboarding session not found.",
  "code": "DAEMONX_ONBOARDING_SESSION_NOT_FOUND"
}

6.3. Read-Only Token Used (`403 Forbidden`)

If a read-only developer token attempts to cancel a session:

{
  "success": false,
  "error": "DaemonX token does not have write permissions.",
  "code": "DAEMONX_TOKEN_READ_ONLY"
}

7. TypeScript Contracts

export interface DaemonxOnboardingSessionCancelResponse {
  success: true;
  onboarding_session: {
    id: string;
    status: 'cancelled';
    external_customer_ref: string | null;
    external_location_ref?: string | null;
    external_counter_ref?: string | null;
    counter_name: string;
    environment: 'live' | 'sandbox';
    is_sandbox: boolean;
    counter_id?: string | null;
    completed_at?: string | null;
    expires_at: string;
    created_at: string;
  };
}

8. cURL Example

curl -X POST https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions/4b68ff5e-f001-4475-8025-a741544256eb/cancel \
  -H "Authorization: Bearer nyx_daemonx_live_6b431eda073e6cb462bd0a9971687376ef5481887c46dfa688bcb618982fc905" \
  -H "Content-Type: application/json" \
  -d '{}'

Cancel Pairing Session