CKO-03: External Checkout — Anonymous Variant

When to use this

Use the anonymous variant when:

You manage the end-user relationship entirely in your own system
You do not want kurnl to store subscriber PII
You use your own invoicing and billing — kurnl should not issue invoices on your behalf

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

If you want kurnl to manage subscriber records and billing, use CKO-03 direct delivery instead.

How it works

When a subscriber selects a plan on the kurnl Marketplace, kurnl creates a checkout session and redirects them to your checkout URL with a session_id query parameter. Your checkout page reads this session to get the plan details, collects payment in your own system, then notifies kurnl to provision the port.

Step-by-step

1. Configure your checkout URL

Identical to direct delivery — see CKO-03 Direct: Step 1.

2. Read the session from the redirect URL

When the subscriber lands on your checkout page, the URL will contain ?session_id=<uuid>. Call the sessions endpoint to retrieve the plan details:

curl https://middleware.bso-projects.com/partner/external-checkout/sessions/SESSION_ID \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET"

Response — 200 OK:

{
  "id": "c3d4e5f6-...",
  "service_provider_document_id": "a1b2c3d4-...",
  "plan_version_id": "f7e8d9c0-...",
  "location_hash": "ab12cd34ef",
  "delivery_mode": "direct",
  "status": "pending",
  "expires_at": "2024-06-08T15:30:00Z"
}

Use the returned plan_version_id to call GET /partner/marketplace/plans/{plan_version_id} if you want to display the plan name and price to the subscriber before they pay.

Sessions expire after 30 minutes. An expired (or cancelled) session returns 410 Gone — redirect the subscriber back to the Marketplace to start a fresh checkout.

3. Collect payment in your own system

Display the plan details and handle the full checkout and payment in your own system. kurnl receives no customer data.

4. Call kurnl after successful payment

Once payment succeeds, notify kurnl to provision the port. You have two options:

Option A — pass `session_id` (recommended)

The simplest path. kurnl reads the plan, location, and provider directly from the session — you only need to supply your own internal subscription identifier.

curl -X POST https://middleware.bso-projects.com/partner/external-checkout/anonymous-complete \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET" \
  -d '{
    "session_id": "c3d4e5f6-...",
    "external_subscription_id": "your-internal-id-123"
  }'

Option B — pass fields explicitly (legacy / non-Marketplace flows)

Use this when you are not going through a kurnl Marketplace session — for example, a direct link from your own website where you already know the plan and location.

curl -X POST https://middleware.bso-projects.com/partner/external-checkout/anonymous-complete \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET" \
  -d '{
    "service_provider_document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "plan_version_id": "f7e8d9c0-b1a2-3456-cdef-012345678901",
    "delivery_mode": "direct",
    "location_hash": "ab12cd34ef",
    "external_subscription_id": "your-internal-id-123"
  }'

Successful response — 200 OK (both options):

{
  "subscription_id": "8c4a1b9e-...",
  "external_subscription_id": "your-internal-id-123",
  "delivery_mode": "direct",
  "subscription_status": "ACTIVE",
  "job_id": "3d6e8f12-...",
  "message": "Provisioning started",
  "idempotent_replay": false
}

No subscriber_id is returned — no subscriber record is created. Store the subscription_id to correlate with webhook events.

5. Handle webhook events

Event	When	Key fields
`provisioning.completed`	~30 seconds — 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. See Webhooks for signature verification and retry behaviour.

Field reference

`GET /partner/external-checkout/sessions/{session_id}`

Field	Type	Notes
`id`	UUID	The session ID — pass this to `anonymous-complete` as `session_id`
`service_provider_document_id`	UUID	Your provider UUID
`plan_version_id`	UUID	The plan the subscriber selected
`location_hash`	string	10-char location identifier for direct delivery
`unit_id`	UUID	MDU unit ID for home-drop delivery
`delivery_mode`	`"direct"` \| `"home_drop"`	Delivery mode set when the session was created
`status`	`"pending"` \| `"redirected"` \| `"completed"`	`completed` after a successful `anonymous-complete` call. Expired/cancelled sessions return `410 Gone` instead of a body.
`expires_at`	ISO datetime	Session TTL — redirect back to Marketplace if expired

`POST /partner/external-checkout/anonymous-complete`

Field	Type	Required	Notes
`session_id`	UUID	Yes (Option A)	Pass to let kurnl read plan/location from the session; makes the individual fields below optional
`external_subscription_id`	string	Yes (always)	Your own per-subscription identifier — acts as idempotency key
`service_provider_document_id`	UUID	Yes (Option B)	Your provider UUID
`plan_version_id`	UUID	Yes (Option B)	The plan to activate
`delivery_mode`	`"direct"` \| `"home_drop"`	No	Defaults to `"direct"`
`location_hash`	string (10 hex chars)	Yes (Option B, direct)	Location identifier
`unit_id`	UUID	Yes (Option B, home_drop)	MDU unit identifier
`mac_address`	string	No	Enables port security (static MAC binding) on the switch

Error handling

Status	Error	What to do
401	`X-Webhook-Secret header required`	Add the header
401	`Invalid webhook secret`	Check your secret in the dashboard
404	`Location not found for location_hash`	Hash expired or invalid
410	`Session expired`	Redirect the subscriber back to the Marketplace
429	Rate limit exceeded	120 requests/minute per IP

On 5xx errors or network timeout: Safe to retry — the request is idempotent. The same external_subscription_id (or session_id) returns the existing subscription_id rather than creating a duplicate.

Getting Started

Operator Guides

Integration Guides

AI Support Agent

CKO-03: External Checkout — Anonymous Variant

When to use this

How it works

Step-by-step

1. Configure your checkout URL

2. Read the session from the redirect URL

3. Collect payment in your own system

4. Call kurnl after successful payment

Option A — pass `session_id` (recommended)

Option B — pass fields explicitly (legacy / non-Marketplace flows)

5. Handle webhook events

Field reference

`GET /partner/external-checkout/sessions/{session_id}`

`POST /partner/external-checkout/anonymous-complete`

Error handling

​When to use this

​How it works

​Step-by-step

​1. Configure your checkout URL

​2. Read the session from the redirect URL

​3. Collect payment in your own system

​4. Call kurnl after successful payment

​Option A — pass session_id (recommended)

​Option B — pass fields explicitly (legacy / non-Marketplace flows)

​5. Handle webhook events

​Field reference

​GET /partner/external-checkout/sessions/{session_id}

​POST /partner/external-checkout/anonymous-complete

​Error handling

When to use this

How it works

Step-by-step

1. Configure your checkout URL

2. Read the session from the redirect URL

3. Collect payment in your own system

4. Call kurnl after successful payment

Option A — pass `session_id` (recommended)

Option B — pass fields explicitly (legacy / non-Marketplace flows)

5. Handle webhook events

Field reference

`GET /partner/external-checkout/sessions/{session_id}`

`POST /partner/external-checkout/anonymous-complete`

Error handling