# MVP-TASK-033 — Surfboard Demo integration discovery and design

**Status:** Implemented  
**Parent:** MVP-TECH-002-S01–S03

## Objective and required behavior

Define the evidence-backed Surfboard integration design for payments and its Swedish ECR service.
Fetch `https://surfpay.ai/llms.txt`, follow its authoritative developer/API links, obtain no
secrets, and record dated conclusions, unknowns, environment topology, and release implications
in-repo.

## Scope, areas, and non-goals

Cover the selected in-store flow and hardware assumptions; integer minor-unit amounts and numeric
ISO 4217 currency (`752` for SEK); tax-inclusive line items/VAT; order/payment initiation and
status; definitive versus unknown outcomes; cancellation; polling/webhooks and signature
verification; idempotency and stable references; Demo authentication and base-URL configuration;
partner, merchant, store, terminal, ECR and receipt identifiers; `ecrEnabled`; register creation and
state; open/close shift and end-of-day; control-unit and Skatteverket declaration data; receipt
delivery; X/Z reports; and Demo-to-Live certification.

Prefer an ADR or dedicated discovery record. Specify one provider-neutral payment port and the
smallest separate fiscal/ECR port needed by the application; do not widen domain types with Carbon
API shapes. Define local/test as the deterministic fake, staging as Surfboard Demo, and production
as the same adapter configured with Live URL/credentials after approval. Document empty environment
variable names and secret ownership, redacted logging, webhook ingress/authentication, timeouts,
retry rules, and reconciliation ownership. Do not expose credentials, provision charged ECR
resources casually, make Live calls, handle card data, or block fake-backed work.

## Evidence and acceptance

Reference all three IDs in the record. Accept when every question has a sourced yes/no/unknown; Demo
prerequisites and any human-owned account/ECR/Skatteverket steps are explicit; the adapter,
configuration, secret, logging, webhook, and reconciliation designs are reviewable; production
requires no source-code edit; traceability is updated; and documentation-only DoD checks pass.
Handoff identifies the exact prerequisites for task 034.

## Delivered evidence

[ADR 004 — Surfboard payment and fiscal (ECR) integration discovery](../../../decisions/004-surfboard-integration-discovery.md)
is the discovery record. It carries all three scenario IDs, dates every source to 2026-10-09
(`https://surfpay.ai/llms.txt` payload 0.3.0 plus the linked developer index, guides, skills, and
the Carbon OpenAPI 3.1 spec, all fetched without credentials), answers all twenty discovery
questions with Yes/No/Unknown and a source, and keeps every unresolved item in an explicit unknowns
register rather than inventing behaviour.

The record fixes the two port designs (the existing neutral `CheckoutGateway` plus the new smallest
`FiscalGateway`), the fake/Demo/Live environment topology with configuration-only production
switching, the empty `SURFBOARD_*` environment variable names and secret ownership, redacted
logging, webhook ingress with HMAC-SHA512 raw-body verification, timeout and retry rules that never
auto-repeat an initiation, and reconciliation ownership. It lists the Demo prerequisites, the
human-owned account/ECR/Skatteverket/Live steps, and the exact nine-point MVP-TASK-034 handoff.

No test was added: this is a documentation-only change with no executable behaviour, and the
existing static provider-boundary guard (`checkout-boundary.test.mjs`) already covers the unchanged
code boundary. Traceability, the task index, architecture, tech stack, current state, and handover
are updated in the same task.