CKO-03: External Checkout — Direct Delivery

When to use this

Use CKO-03 direct delivery when:

The subscriber’s building is classified as first-line in kurnl — the switch port is known (captive-portal flow, location_hash) or kurnl resolves the suite’s own port (address search, QR landing), so kurnl can provision it directly
Or the building is second or third line and the suite’s router is already online — kurnl provisions the suite’s port the same way, without a visit
You run your own checkout page and want full control over the payment and signup experience
Your plan is listed on the kurnl marketplace and you want subscribers to start there

If the building is second or third line and the suite’s router is not online, or the building is unclassified (even when the router is online), the same callback creates an operator install job instead. See CKO-03 home-drop delivery.

How kurnl routes the callback

For POST /partner/external-checkout/complete with a session_id, the delivery_mode field is ignored. kurnl resolves the session’s building_id to the building’s line type — operator-side configuration that partners never set — checks whether the suite’s router is already online, and routes:

Building line type	Session carries	What happens	Response
`first`	a resolvable `location_hash`	Port provisioned directly	200 with `job_id` — this guide
`first`	a `unit_id` and no port	The suite’s port provisioned (`409 suite_not_wired` when none is wired); a suite with several connections is held for the operator’s confirmation — see Shared suites	200 with `job_id` (`null` while held)
`second` / `third`	a `unit_id` whose router is already online (suite of one)	The suite’s port provisioned	200 with `job_id` — this guide
`second` / `third`	a `unit_id` whose router is not online, or a shared suite	Operator install job, subscription `PENDING_INSTALL`	200 without `job_id` — see home-drop
unclassified (NULL)	a `unit_id`	Operator install job, even when the suite’s router is online	200 without `job_id` — see home-drop

A router counts as online when it answered within the last 15 minutes. kurnl checks this when the callback arrives, so a suite that was ready when the shopper chose it can still take the install path. GET /serviceability/units shows the state per suite as cpe_ready. kurnl fails closed: the switch is provisioned without a visit only on an explicit first-line building, or for a second- or third-line suite whose router is already online. When kurnl cannot read the router’s state, the order takes the install path. A session carrying neither a port nor a unit_id is rejected with 422 (see error handling).

Because the line type is operator configuration and the router’s state can change, your integration cannot know in advance which response it will get. Treat job_id as optional: if it is present, provisioning has started; if it is absent, the subscription is pending installation. Handle 422 gracefully by surfacing the error to support rather than retrying.

delivery_mode still controls the routing only for legacy no-session payloads (see the explicit-fields reference below).

How it works

Step-by-step

1. Configure your checkout URL

In the provider dashboard, open Checkout (/checkout-settings) and set the Store checkout URL. When a subscriber selects your plan, the kurnl Marketplace creates a checkout session and redirects them to your page with a single query parameter appended:

Parameter	Description
`session_id`	UUID of the checkout session. Everything else (plan, location, building, provider) lives on the session.

Example redirect:

https://checkout.yourcompany.com/internet?session_id=c3d4e5f6-...

2. Read the session

On page load, fetch the session to get the plan and location the subscriber selected:

curl https://middleware.kurnl.ca/partner/external-checkout/sessions/SESSION_ID \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET"

{
  "id": "c3d4e5f6-...",
  "service_provider_document_id": "a1b2c3d4-...",
  "plan_version_id": "f7e8d9c0-...",
  "location_hash": "ab12cd34ef",
  "building_id": "d4e5f6a7-...",
  "status": "pending",
  "expires_at": "2026-07-01T12:30:00Z",
  "plan_versions": { "retail_price_monthly": 79.0, "plans": { "name": "Fibre 500" } }
}

The embedded plan_versions object gives you the plan name and price to display. Reading the session here also protects it: from your first read on, it no longer expires, so a slow payment cannot cost the order. A session your page never reads expires 2 hours after it was created, and a 410 Gone then means the subscriber must restart from the Marketplace. See Checkout Sessions for the full session API, including the PATCH upsell endpoint for swapping plans mid-checkout.

Legacy handoff: integrations built before the session flow received location_hash, plan_version_id, and service_provider_document_id as individual query parameters. That handoff is obsolete — new integrations should always read the session. The callback still accepts explicit fields for non-Marketplace flows (see the field reference below).

3. Collect payment and subscriber details

Run your normal checkout flow. Collect the subscriber’s:

Name, email, phone (optional)
Invoice address (the address printed on the invoice)
Payment method

kurnl does not receive payment details. You handle payment processing entirely on your side.

4. Call kurnl after successful payment

After payment succeeds, POST to /partner/external-checkout/complete with the session_id and the subscriber’s details. kurnl reads the plan, location, building, and provider from the session — you never re-send them:

curl -X POST https://middleware.kurnl.ca/partner/external-checkout/complete \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET" \
  -d '{
    "session_id": "c3d4e5f6-...",
    "subscriber": {
      "email": "alice@example.com",
      "username": "alice",
      "password": "secure-password-123",
      "customer_type": "RESIDENTIAL",
      "mac_address": "AA:BB:CC:DD:EE:FF",
      "invoice_contact_detail": {
        "firstname": "Alice",
        "lastname": "Smith",
        "email": "alice@example.com",
        "phonenumber": "+16045551234"
      },
      "contract_contact_detail": {
        "firstname": "Alice",
        "lastname": "Smith",
        "email": "alice@example.com"
      },
      "invoice_address": {
        "street": "Maple St",
        "housenumber": "42",
        "postalcode": "A1B 2C3",
        "city": "Vancouver",
        "province": "BC",
        "country": "Canada"
      }
    }
  }'

Successful response — 200 OK (provisioned directly — first-line building, or a suite whose router is already online):

{
  "job_id": "3d6e8f12-...",
  "subscription_id": "8c4a1b9e-...",
  "subscriber_id": "2f5d7a0c-...",
  "message": "Provisioning started"
}

Successful response — 200 OK (install job — a suite whose router is not online, a shared suite, or an unclassified building):

{
  "subscription_id": "8c4a1b9e-...",
  "subscriber_id": "2f5d7a0c-...",
  "message": "Subscription pending installation. Call /provisioning/confirm-install when the port is ready."
}

No job_id in the second shape — provisioning has not started; the subscription is PENDING_INSTALL and kurnl fires subscription.pending_install instead of subscription.activated. See home-drop for what happens next. Store the subscription_id and subscriber_id in your system — you’ll need them for any future subscriber management calls. The callback is idempotent: a second call with the same session_id returns the existing subscription and the real subscriber_id, without job_id, with the message "Subscription already exists for this session_id (idempotent replay)".

Shared suites

A suite with several connections (200-1, 200-2 behind postal suite 200) is re-anchored to its first free connection and held until the kurnl operator confirms which connection is the customer’s. On a first-line building the callback answers 200 with "job_id": null, "route": "provision" and "unit_confirmation_pending": true; the subscription is PENDING and provisioning does not start. Retrying the callback with the same session_id returns the existing order; without one, a repeat returns the existing order on the provision route and 409 Unit already has a pending or active subscription on the install route. When every connection is taken the callback is refused with 409 no_free_connection. Details: POST /external-checkout/complete.

5. Handle webhook events

kurnl fires events to your configured webhook_url at each stage:

Event	When	Key fields
`subscription.activated`	Immediately after your callback (provisioned path only) — for a shared-suite order, when the operator confirms the connection instead	`subscription_id`, `subscriber_id`, `plan_version_id`, `location_hash`
`subscription.pending_install`	Immediately after your callback (install-job path only)	`subscription_id`, `subscriber_id`, `plan_version_id`, `unit_id`
`provisioning.completed`	~30 seconds later, port is live	`job_id`, `subscription_id`
`provisioning.failed`	If SSH provisioning fails	`job_id`, `subscription_id`, `error`

At provisioning.completed, the subscriber’s internet is live. This is the right moment to send them a confirmation email. See Webhooks for signature verification and retry behaviour.

Field reference

Session flow (recommended)

Field	Type	Notes
`session_id`	UUID	From the `?session_id=` redirect parameter. Supplies plan, location, building, provider, and MAC from the session. Routing is decided by the building’s line type and whether the suite’s router is already online.
`partner_reference`	string (optional)	Your own reference, stored on the session
`subscriber`	object	Required — see subscriber fields below

Explicit fields (legacy, non-Marketplace flows only)

Without a session_id, routing is controlled by delivery_mode:

Field	Type	Notes
`service_provider_document_id`	UUID	Your provider UUID — used to look up your webhook secret
`plan_version_id`	UUID	The plan to activate
`delivery_mode`	`"direct"` \| `"home_drop"`	Defaults to `"direct"`. Ignored when `session_id` is present.
`location_hash`	string (10 hex chars)	Required for `direct` delivery
`unit_id`	UUID	Required for `home_drop` delivery

Subscriber fields (required in both flows)

Field	Type	Notes
`subscriber.email`	string	Kurnl account identifier. Existing accounts are reused.
`subscriber.username`	string (min 3)	Display name
`subscriber.invoice_contact_detail`	object	See contact detail fields below
`subscriber.contract_contact_detail`	object	Can be identical to invoice contact
`subscriber.invoice_address`	object	See address fields below

Optional fields

Field	Type	Notes
`subscriber.password`	string (min 8)	Only set for new accounts. Existing accounts keep their password.
`subscriber.customer_type`	`"RESIDENTIAL"` \| `"BUSINESS"`	Defaults to `"RESIDENTIAL"`
`subscriber.mac_address`	string	Enables port security (static MAC binding) on the switch. When the session carries a MAC and they disagree, the session wins.

Contact detail fields

Field	Type
`firstname`	string
`lastname`	string
`email`	string
`phonenumber`	string (optional)
`company`	string (optional)

Address fields

Field	Type
`street`	string
`housenumber`	string
`postalcode`	string
`city`	string
`province`	string
`country`	string (default: `"Canada"`)
`unitnumber`	string (optional)
`floor`	string (optional)

Error handling

Status	Error	What to do
401	`X-Webhook-Secret header required`	Add the header
401	`Invalid webhook secret`	Check your secret matches what’s in the dashboard
403	`Plan version does not belong to your service provider`	Wrong `plan_version_id` for your account
404	`Location not found for location_hash`	The hash didn’t match any location record — subscriber may have used an expired link
404	`Session not found`	Wrong `session_id`
410	Session expired / cancelled	Send the subscriber back to the Marketplace to restart checkout (nested body — see below)
409	`no_free_connection`	Every connection of the shared suite is taken — send the subscriber back to pick another suite
422	`First-line building requires a resolvable port (location_hash) or a unit; the session carries neither.`	The session has no port and no suite — contact kurnl support / the operator
422	`Building line type '…' requires an operator install job, but the session has no unit_id — refusing to provision.`	Same — session/building mismatch, do not retry
422	`Invalid location_hash format`	Must be exactly 10 hex characters
400	The sign-in service’s reason, e.g. `Password should be at least 6 characters.`	It refused `subscriber.password` for the new account — nothing was created; ask the subscriber for another password and complete the session again
422	`detail.code = "speed_tier"` (object: `code`, `message`, `speed_tier_mbps`, `plan_download_mbps`)	The plan is faster than the building delivers — nothing was created; refund or move the subscriber to a plan within the tier
422	`detail.code = "plan_audience"` (object: `code`, `message`, `target_audience`)	A plan for existing customers only is not listed and not orderable — nothing was created; offer a plan from the plan list
503	`Could not verify the building's speed tier; try again.`	Retry
422	`detail.code = "not_covered"` (object: `code`, `message`, `building_id`)	Your provider does not cover the building (no ticked division, picked building or contract) — nothing was created; offer the subscriber a building in your coverage or ask kurnl about it
503	`Could not verify the building's coverage; try again.` · `Could not read the line's building; try again.`	Retry — nothing was created
422	`detail.code = "plan_not_offered"` (object: `code`, `message`, `building_id`)	Your provider does not offer this plan in the building — nothing was created; offer a plan the building offers (see `plans` of the address check) or add the plan under Coverage
503	`Could not verify the building's plan offer; try again.`	Retry — nothing was created
400	`Plan version not active`	The plan’s effective date window has passed
429	Rate limit exceeded	120 requests/minute

410 body shape — unlike other errors, the detail is a nested object:

{
  "detail": {
    "detail": "Session expired",
    "expired_at": "2026-07-01T12:30:00Z"
  }
}

({"detail": {"detail": "Session cancelled"}} for cancelled sessions — no expired_at.) On 5xx errors: Safe to retry the full request. kurnl rolls back any partial state automatically on failure. On network timeout: Retry the request — it is idempotent. The same session_id returns the existing subscription. The explicit-fields flow is idempotent too: a retry with the same subscriber email + plan_version_id + location returns the existing subscription with the message "Subscription already exists (idempotent replay)" (or "Provisioning already in progress" while the job is still running; job_id may be empty on replay).

Anonymous variant

If you own the end-user relationship and don’t want kurnl to store subscriber PII, use the anonymous variant instead. You provide an external_subscription_id (your own identifier) instead of a subscriber object. kurnl provisions the port but creates no subscriber record.

With the anonymous variant, subscribers have no kurnl self-service portal access and kurnl cannot issue invoices on your behalf.

Getting Started

Provider Guides

Operator Guides

Partner Integration

AI Support Agent

Changelog

CKO-03: External Checkout — Direct Delivery

When to use this

How kurnl routes the callback

How it works

Step-by-step

1. Configure your checkout URL

2. Read the session

3. Collect payment and subscriber details

4. Call kurnl after successful payment

Shared suites

5. Handle webhook events

Field reference

Session flow (recommended)

Explicit fields (legacy, non-Marketplace flows only)

Subscriber fields (required in both flows)

Optional fields

Contact detail fields

Address fields

Error handling

Anonymous variant

​When to use this

​How kurnl routes the callback

​How it works

​Step-by-step

​1. Configure your checkout URL

​2. Read the session

​3. Collect payment and subscriber details

​4. Call kurnl after successful payment

​Shared suites

​5. Handle webhook events

​Field reference

​Session flow (recommended)

​Explicit fields (legacy, non-Marketplace flows only)

​Subscriber fields (required in both flows)

​Optional fields

​Contact detail fields

​Address fields

​Error handling

​Anonymous variant

When to use this

How kurnl routes the callback

How it works

Step-by-step

1. Configure your checkout URL

2. Read the session

3. Collect payment and subscriber details

4. Call kurnl after successful payment

Shared suites

5. Handle webhook events

Field reference

Session flow (recommended)

Explicit fields (legacy, non-Marketplace flows only)

Subscriber fields (required in both flows)

Optional fields

Contact detail fields

Address fields

Error handling

Anonymous variant