Skip to main content
Version: v2

Documentation Rules

The 3‑Document Rule​

Ask yourself:

❓ Am I explaining WHAT it means? → Business doc

❓ Am I explaining HOW to call or track it? → Integration doc

❓ Am I explaining HOW it works internally? → Internal doc

1️⃣ Business Use Case Document — What & Why​

Audience: Product, Business, Support, Leadership, Engineers (for context)

Purpose:

  • Explain what the feature does
  • Explain why it exists
  • Explain what outcomes to expect

Includes:

  • Real‑world examples
  • Business rules & constraints
  • Scenarios and edge cases
  • Lifecycle meaning (Status → Meaning → Action)

Does NOT include:

  • API endpoints
  • Request/response payloads
  • Polling or webhook mechanics
  • Internal system states

✅ Example:

Split Tender Payments allow customers to pay with two cards.
If either card fails, the payment fails and no money is captured.

2️⃣ Integration Document — How to Integrate & Operate​

Audience: API consumers, Integration engineers, CCG Platform Engineers

Purpose:

  • Explain how to call the API
  • Explain how to track status
  • Explain how to recover from failures

Includes:

  • API endpoints and headers
  • Sample request / response (use‑case specific)
  • Lifecycle tracking (polling + webhooks)
  • Retry rules and idempotency
  • Error handling guidance

Does NOT include:

  • Business justification
  • User‑level explanations
  • Internal DB / processor states (unless marked internal)

✅ Example:

Poll the parent paymentId.
Listen for PAYMENT_SUCCEEDED or PAYMENT_FAILED.
Do not poll allocation IDs.

3️⃣ Internal Engineering Document — How It Works Inside​

Audience: CCG / Platform Engineers only

Purpose:

  • Explain internal sequencing
  • Explain processor behavior
  • Explain internal statuses & rollback logic

Includes:

  • Architecture diagrams
  • Processor‑level flows
  • Internal status combinations
  • Implementation notes

Rule:

⚠️ Must always be wrapped in
<Audience include="internal">

✅ Example:

Internally, Split Tender uses PRE‑AUTH + CAPTURE with automatic cancellation on partial failure.

🧠 Lifecycle Rule (Most Important)​

🔁 Lifecycle: Where It Belongs​

✅ Lifecycle meaning → Business Document
✅ Lifecycle tracking → Integration Document
✅ Lifecycle implementation → Internal Document ``

Examples​

Business Use Case (Lifecycle Meaning)​

Status Reference​

StatusMeaningMerchant Action
COMPLETEDBoth cards charged successfullyFulfill the order
FAILEDOne or more cards failedPrompt customer to retry
PENDINGPayment is still processingWait for webhook

Integration Document (Lifecycle Tracking)​

Status Handling​

Polling Guidelines​

  • Poll using paymentId or merchantTransactionId
  • Do not poll individual allocation IDs

Webhooks​

  • PAYMENT_SUCCEEDED → transaction completed
  • PAYMENT_FAILED → transaction failed (not final if retries remain)

Status Computation​

  • All allocations succeed → COMPLETED
  • Any allocation fails → FAILED

Internal Engineering (Lifecycle Implementation)​

Internal Status Flow​

  • AUTHORIZED → CAPTURE_INITIALIZED → COMPLETED
  • AUTHORIZED → FAILED → CANCELLED (rollback)

Internal statuses are not exposed to merchants.

🔍 Doc Structure Lint — What to Expect​

Automated Check — Runs on Every PR

scripts/lintDocStructure.js (via yarn lint:docs) validates every file under docs/01-business/ and docs/03-developers/ against its guideline. Violations are posted as a PR comment and block merge.

Run it locally before pushing:

yarn lint:docs
node scripts/lintDocStructure.js --files path/to/your-doc.md

Which Files Are Linted​

FolderGuideline Applied
docs/01-business/**Business Use Case Guidelines
docs/03-developers/** (except error-codes)Integration Document Guidelines
docs/03-developers/5-convenient-checkout-api/4-error-codes/**API Error Code Guidelines

Always skipped: docs/contributing-guide/**, docs/whats-new/**, index.md / index.mdx, _category_.json

❌ Check 1 — Missing Required Sections​

Every doc must contain these H2 headings:

GuidelineRequired ## Headings
BusinessKey Benefits · How It Works · Business Rules · Scenarios · Related Documentation
Integration[Feature] Processing Flow · API Request · API Response · Status Handling · Error Handling · FAQ · Integration Checklist · Related Documentation
Error CodesError Summary · Error Details

Failure message:

Missing sections:
  • Key Benefits
  • How It Works

Fix: Add the missing ## heading and its content.

❌ Check 2 — Wrong Section Order​

Required headings that are present must appear in the same relative order as the guideline defines.

Failure message:

Order issues:
  • "Scenarios" should appear after "Business Rules" per guideline — found in wrong order

Fix: Re-order sections to match the guideline sequence.

❌ Check 3 — Missing Required Content Block​

Certain admonitions must appear in every doc regardless of headings:

GuidelineRequired BlockWhere
Business:::tip Get StartedAfter H1 intro, before ## Key Benefits
Integration:::tip Integration DetailsNear the top, before ## API Request

Failure message:

Missing required content:
  • Business docs must include a `:::tip Get Started` admonition after the intro.

Fix — Business docs:

:::tip[Get Started]
To integrate [Feature Name], follow the [Integration Guide](/docs/developers/...) for step-by-step instructions and API details.
:::

Fix — Integration docs:

:::tip[Integration Details]
- **Prerequisites:** …
- **Endpoint:** …
- **Scope:** …
- **API Version:** …
:::

❌ Check 4 — Forbidden Content (Business Docs Only)​

Business docs must NOT contain any of the following
What's ForbiddenExampleFix
HTTP verb + versioned pathPOST /v2/paymentsMove to integration doc
curl commandscurl -X POST ...Move to integration doc
Shell/curl code blocks```bash · ```curlMove to integration doc
API Version referencesAPI Version: v2Remove — business docs are version-agnostic
OpenAPI / Swagger mentionsopenapi, swaggerLink from integration doc instead
## API Request / ## API Response sections—These belong in integration docs
## API Endpoint / ## API Spec references—Same

Exception: Content inside <Audience include="internal"> is skipped.

Failure message:

Content violations:
  • Line 42: Business docs must not contain API endpoint references.
    → POST /v2/payments/allocations

Fix: Remove the flagged content and add a link under ## Related Documentation instead.

ℹ️ How Headings Are Matched​

  • Leading numbering stripped: ## 3. Business Rules → Business Rules
  • Trailing dash descriptions stripped: ## Webhooks — Event Reference → Webhooks
  • Markdown formatting stripped: ## **Key Benefits** → Key Benefits
  • Case-insensitive, non-alphanumeric characters ignored
  • Headings inside fenced code blocks are ignored
  • [Feature Name] Processing Flow uses a suffix match — any ## ending with Processing Flow satisfies the requirement (e.g., ## Disputes Processing Flow)

🛠 Quick Fix Checklist​

Before pushing, run yarn lint:docs and confirm:

  • Every required ## section exists in the correct order
  • Business docs have a :::tip Get Started block after the H1
  • Integration docs have a :::tip Integration Details block near the top
  • Business docs contain no API endpoints, curl commands, or API Version references
  • Internal-only technical details are wrapped in <Audience include="internal">