CKO-03: External Checkout — Direct Delivery

When to use this

Use CKO-03 direct delivery when:

The subscriber’s building is already wired — a switch port exists and is assigned to their unit
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 subscriber’s unit does not yet have a port installed, use CKO-03 home-drop delivery instead.

How it works

Step-by-step

1. Configure your checkout URL

In Dashboard → Settings → Integration, set your external_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, delivery mode, 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",
  "delivery_mode": "direct",
  "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. Sessions expire after 30 minutes — a 410 Gone 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, 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:

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

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 without re-provisioning.

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	`subscription_id`, `subscriber_id`, `plan_version_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, provider, delivery mode, and MAC from the session.
`partner_reference`	string (optional)	Your own reference, stored on the session
`subscriber`	object	Required — see subscriber fields below

Explicit fields (non-Marketplace flows only)

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
`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
`delivery_mode`	`"direct"` \| `"home_drop"`	Defaults to `"direct"`
`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

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` / `Session cancelled`	Send the subscriber back to the Marketplace to restart checkout
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 per IP

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 (or, in the explicit-fields flow, the same email + plan_version_id combination) returns the existing subscription rather than creating a duplicate.

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

Integration Guides

AI Support Agent

CKO-03: External Checkout — Direct Delivery

When to use this

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 (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 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 (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 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 (non-Marketplace flows only)

Subscriber fields (required in both flows)

Optional fields

Contact detail fields

Address fields

Error handling

Anonymous variant