Version: v2

UI Integration Document Guidelines

This template standardizes UI integration documentation for frontend engineers, platform engineers, and QE/automation engineers. Think of a UI integration doc as "How do I integrate, operate, and test your UI safely?" — not product marketing.

When to Use This Template

Use this template when documenting a UI component, widget, or hosted page that consuming teams need to embed, launch, or automate (e.g., the Checkout UI, payment widget, 3DS challenge frame). For backend API documentation, refer to the Integration/API Document Guidelines.

Internal-Only Content

Use <Audience include="internal"> to wrap any content that should only be visible to the internal engineering team — such as sequence diagrams, feature-flag internals, or processor-level behaviour.

<Audience include="internal">

### Internal Section Title

Content only visible to internal engineers.

</Audience>

✅ Use for: internal state machines, processor-specific UI flows, internal config sources.
❌ Do not use for: merchant-facing launch URLs, public error codes, standard integration steps.

Standard Section Headings

Every UI integration document must follow these section headings in this order.

#	Section Heading	Purpose	Required?
—	`# [UI Name]` (H1)	2–3 sentence intro: what it is, who uses it, when to use it vs not	✅ Always
1	`## Integration Details`	Quick-reference admonition: entry point, session dependency, versions, links	✅ Always
2	`## Integration Models`	Supported embed modes (redirect, iFrame, modal, WebView) with trade-offs	✅ Always
3	`## Entry Contract`	URL pattern, required/optional query params, tokens — treat like an API Request	✅ Always
4	`## Authentication & Security`	Who authenticates whom, token type, lifetime, refresh expectations	✅ Always
5	`## UI–API Interaction Map`	Table mapping UI actions → backend API calls, trigger conditions, blocking flag (internal only)	Internal only
6	`## State Machine / Lifecycle`	UI states, transitions, persistence, recoverability, terminal states	✅ Always
7	`## Error Handling`	Map error sources/codes → UI behaviour, retryability	✅ Always
8	`## Configuration & Feature Flags`	Config keys, sources, and impact on UI behaviour	When config exists
9	`## Versioning & Backward Compatibility`	UI version vs API version matrix, migration guidance, breaking changes	When multiple versions
10	(Section intentionally omitted — see automation best practices elsewhere)
11	`## Known Limitations`	Unsupported browsers/modes, UX constraints, compliance blocks	✅ Always
12	`## Related Documentation`	Cross-reference links to API docs, business docs, error code docs	✅ Always

What NOT to include:

❌ Business justification or product marketing
❌ End-user training or UX rationale
❌ Full API specs (link to them instead)
❌ Design discussions or visual design decisions

1. Overview (H1 introduction)

Purpose: Orient the reader in 2–3 sentences. State what the UI is, when to use it, and who the audience is.

Include:

What the UI component does and what problem it solves for integrators
When to use it vs an alternative (API-only flow, different widget version)
Supported integration models overview (expand in Section 2)

Example:

The Checkout UI enables merchants to collect payment details securely and complete a checkout session created via CCG APIs. It supports redirect, iFrame, and modal integration models. This guide covers how to embed the UI, understand UI–API contracts, handle states and errors, and automate UI flows confidently.

2. Integration Details

Purpose: Quick-reference summary of the entire integration surface. Use a :::tip admonition.

:::tip[Integration Details]
- **Enablement/Prerequisites:** Session must be created via [Create Session API](/docs/...). Merchant account must be configured for UI.
- **Entry Point:** `GET /checkout-ui?sessionId=<id>&merchantId=<id>`
- **Supported Embed Models:** Redirect, iFrame, Modal
- **UI Version:** v3
- **Required API Version:** v2 (v1.3+ minimum)
- **Session Token Lifetime:** 15 minutes
- **Sandbox / Test Mode:** Append `?env=sandbox` to simulate flows. See [Testing & Automation Hooks](#testing--automation-hooks).
- **Error Codes:** See UI Error Codes for UI-surface errors.
:::

3. Integration Models

Purpose: Clearly document every supported way the UI can be consumed, with trade-offs and known constraints per model.

Model	Description	Supported
Redirect	Full-page redirect to hosted UI	✅
iFrame	Embedded inside merchant page	✅
Modal / Widget	JS-injected modal overlay	✅
Native Wrapper	WebView (mobile)	✅

For each supported model, include:

How to launch (URL pattern or JS snippet)
Known constraints (CSP headers, third-party cookie restrictions, X-Frame-Options)
Session / context dependency
Pros and cons relevant to integration teams

Example — iFrame constraints:

The iFrame model requires Content-Security-Policy: frame-ancestors 'self' https://<merchant-domain> and does not support third-party cookie-dependent flows. Use the Redirect model for maximum compatibility.

4. Entry Contract

Purpose: Treat UI launch like an API Request. Document every parameter needed to initialize the UI correctly.

What launches the UI:

GET /checkout-ui

Required:
  sessionId     string   Session token from Create Session API
  merchantId    string   Merchant identifier

Optional:
  locale        string   BCP 47 language tag (default: en-US)
  theme         string   Merchant theme key
  returnUrl     string   Redirect target on completion
  cancelUrl     string   Redirect target on cancel

Guidelines:

Cross-link to the API doc that creates the session — do not duplicate field definitions
Document what happens when required params are missing (error state, redirect, or blank screen)
Document any headers or tokens required in the launch context (e.g., CSP, referrer policy)

5. Authentication & Security

Purpose: Make the trust model explicit. Developers should not have to guess who authenticates whom.

Include:

Who authenticates the user — backend session vs UI-level auth
Token type — JWT, opaque session token, cookie
Token lifetime — and what the UI does when it expires (auto-redirect, error screen, retry)
Refresh expectations — does the UI refresh tokens silently or always require a new session?
CSP and frame policy requirements for iFrame or modal models

Example:

The UI trusts the sessionId issued by the backend (Create Session API).
No direct user authentication is performed in the UI.
If the session expires mid-flow, the UI displays a session-expired error and redirects to cancelUrl.
Token lifetime: 15 minutes, non-refreshable. A new session must be created for re-entry.

5. UI–API Interaction Map

Purpose: Map every significant user action in the UI to the backend API call it triggers. This is the primary reference for QE automation and defect triage.

UI Action	Backend API	Triggered When	Blocking (waits for response)
Page load	`GET /session/{id}`	UI initialized	✅ Yes
Submit payment	`POST /v2/payments`	User clicks "Pay"	✅ Yes
Cancel	`POST /v2/cancel`	User exits / cancels	❌ No (fire-and-forget)
3DS challenge	External 3DS redirect	Card requires 3DS	✅ Yes

Guidelines:

List all API interactions, including fire-and-forget calls
Note which calls block the UI (spinner shown vs background call)
Cross-link each API to its integration doc rather than duplicating request/response details

Include an internal sequence diagram showing the full message flow between UI, CCG Platform, and processors.

7. State Machine / Lifecycle

Purpose: Document UI states like backend transaction states — deterministic and complete.

INIT → LOADED → INPUT → PROCESSING → SUCCESS
                                    → FAILURE
                                    → CANCELLED
                                    → SESSION_EXPIRED

For each state, document:

State	Description	Persisted?	Recoverable on refresh?	Terminal?
INIT	Session validated, UI bootstrapping	No	✅ Yes	❌
LOADED	Form rendered, awaiting input	No	✅ Yes	❌
INPUT	User entering details	No	✅ Yes (form cleared)	❌
PROCESSING	Payment API call in flight	No	❌ No — resumes at LOADED	❌
SUCCESS	Payment confirmed	✅ Yes	✅ Yes	✅
FAILURE	Payment rejected	No	❌ No — new session req	✅
CANCELLED	User or system cancelled	No	❌ No	✅
SESSION_EXPIRED	Session token expired mid-flow	No	❌ No — new session req	✅

8. Error Handling

Purpose: Give developers deterministic, predictable UI behaviour for every error category. Only the following error codes are handled:

Error Code	UI Behaviour	Retryable?
400	Inline field validation message	✅ Yes
401	Full-screen unauthorized error page	❌ No
404	Not found error screen	❌ No
410	Gone/expired session screen	❌ No

Guidelines:

Only these error codes are handled at the UI layer
Map each code to a clear UI behaviour
Cross-link to Error Codes for full code reference
Document the error screen content (heading, body, CTA label) for non-recoverable states

9. Configuration & Feature Flags

Purpose: Document every config key that affects UI behaviour, so integrators can predict what they will see.

Config Key	Source	Impact
`enabledFeatures`	Merchant config	Controls which payment options are visible
`apiVersion`	Merchant config	Determines UI compatibility mode
`paymentModes`	Backend response	Restricts allowed payment flows
`theme`	Query param	Applies merchant visual theme
`locale`	Query param	Sets display language

Guidelines:

State the source of truth for each config (query param, session payload, merchant account setting)
Document what the default value is when the config is absent
Note whether config changes require a new session or take effect immediately

Include any internal feature flags (LaunchDarkly / config service keys) and their rollout status here.

10. Versioning & Backward Compatibility

Purpose: Treat the UI as a versioned contract, just like an API.

UI version vs API version compatibility matrix:

UI Version	Min API Version	Max API Version	Status
v3	v2.0	latest	✅ Current
v2	v1.3	v1.x	⚠️ Deprecated
v1	v1.0	v1.2	❌ End of Life

Include:

Breaking vs non-breaking UI changes — define what constitutes a breaking change (removed elements, changed data-testid values, removed states)
Migration guidance — steps to upgrade from the previous version
Deprecation timeline with dates

Example:

UI v2 requires API v1.3+.
UI v1 will be deprecated on <date>. Migrate to UI v3 following the v2 → v3 migration guide.
Breaking change: The `card-submit-button` data-testid was renamed to `payment-submit-cta` in v3.

12. Known Limitations

Purpose: Be explicit about what does not work. This prevents wasted integration effort and regression surprises.

Include:

Unsupported browsers (e.g., IE11, Safari < 14, in-app browsers with restricted storage)
Unsupported embed modes (e.g., nested iFrames)
Known UX constraints (e.g., form cannot be pre-filled for PCI compliance reasons)
Regulatory / compliance blocks (e.g., certain payment methods not available in specific locales)
Known incidental issues with workarounds if available

Purpose: Connect this doc to the rest of the ecosystem without duplicating content.

Document	Link
Create Session API (entry contract dependency)	[Link to integration doc]
Payment API (UI–API interaction reference)	[Link to integration doc]
Business Use Case doc (what problem this solves)	[Link to business doc]
Error Code Reference	[Link to error codes]
OpenAPI Spec	[Link to API spec]
UI Changelog / Release Notes	[Link to whats-new or changelog]

Appendix

Sample Launch URLs

# Redirect (full-page)
https://<host>/checkout-ui?sessionId=<id>&merchantId=<id>

# Sandbox mode
https://<host>/checkout-ui?sessionId=<id>&merchantId=<id>&env=sandbox

# With optional params
https://<host>/checkout-ui?sessionId=<id>&merchantId=<id>&locale=es-US&theme=dark&returnUrl=https://merchant.com/success

Glossary

Term	Definition
Session	Backend-issued token representing a checkout context
Entry Contract	The set of params required to correctly initialize the UI
Terminal State	A UI state that cannot transition to any other state
data-testid	Stable HTML attribute used for automation targeting
Sandbox mode	UI mode where no real payments are processed

Standard Section Headings​

1. Overview (H1 introduction)​

2. Integration Details​

3. Integration Models​

4. Entry Contract​

5. Authentication & Security​

5. UI–API Interaction Map​

7. State Machine / Lifecycle​

8. Error Handling​

9. Configuration & Feature Flags​

10. Versioning & Backward Compatibility​

12. Known Limitations​

13. Related Documentation​

Appendix​

Sample Launch URLs​

Glossary​

Standard Section Headings

1. Overview (H1 introduction)

2. Integration Details

3. Integration Models

4. Entry Contract

5. Authentication & Security

5. UI–API Interaction Map

7. State Machine / Lifecycle

8. Error Handling

9. Configuration & Feature Flags

10. Versioning & Backward Compatibility

12. Known Limitations

13. Related Documentation

Appendix

Sample Launch URLs

Glossary