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 and the session carries a resolvable location_hash — the switch port is known (captive-portal flow), so kurnl can provision it directly
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 not first-line — or it is first-line but the session carries a suite rather than a port, which is what address search and the QR landing produce — 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 — 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	Operator install job, subscription `PENDING_INSTALL`	200 without `job_id` — see home-drop
`second` / `third` / unclassified (NULL)	a `unit_id`	Operator install job, subscription `PENDING_INSTALL`	200 without `job_id` — see home-drop

kurnl fails closed: only an explicit first-line building with a resolvable port auto-provisions the switch. A session carrying neither a port nor a unit_id is rejected with 422 (see error handling).

Because the line type is operator configuration, 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.bso-projects.com/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)
Billing address
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.bso-projects.com/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 (first-line building — provisioned directly):

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

Successful response — 200 OK (second/third-line or unclassified building — install job):

{
  "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)".

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 (first-line / provisioned path only)	`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.
`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)
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	`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

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

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

​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

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