Version: v2

Business Use Case Document Template

A Business Use Case document describes a real-world business process or scenario — what it does, why it matters, and what outcomes to expect. It should help business, product, support, and engineering teams understand how a feature works from a user's perspective.

important

Keep the language business-focused. Explain what happens and why it matters.
Separate UI and API use cases when the flow, actor actions, or outcomes differ.
Prefer concrete scenarios over abstract descriptions.
Link to related UI, API, technical, or glossary documents where relevant.

Internal-Only Content

Use <Audience include="internal"> to wrap any content that should only be visible to the internal engineering team — such as internal processing notes, processor-specific business rules, or internal escalation details that should not appear in the public-facing business doc.

<Audience include="internal">

### Internal Note

Content only visible to internal engineers — e.g., processor behaviour, internal escalation rules, CCG-specific constraints.

</Audience>

✅ Use for: processor-specific business rules, internal escalation paths, CCG internals not relevant to merchants.
❌ Do not use for: standard business rules, merchant-facing outcomes, scenarios, or status definitions.

Standard Section Headings

Every business use case document must follow these section headings in this order. This keeps all business docs consistent and scannable.

#	Section Heading	Purpose	Required?
—	`# [Feature Name]` (H1)	2–3 sentence intro: what it does, who benefits, when it's used	✅ Always
—	`:::tip Get Started`	Link to the integration guide so developers can jump straight to implementation	✅ Always
1	`## Key Benefits`	Before/after comparison table + real-world example	✅ Always
2	`## How It Works`	Outcome summary table + Standard Flow diagram	✅ Always
3	`## Business Rules`	Pre-Conditions, Post-Conditions, Constraints	✅ Always
4	`## Scenarios`	Standard scenarios table + Edge Cases in `:::danger`	✅ Always
5	`## Notifications`	Webhook events summary table	When webhooks exist
6	`## Status Reference`	Status → Meaning → Action table	When statuses exist
7	`## Related Documentation`	Cross-reference links to technical, API, and related docs	✅ Always

Sub-heading Standards

Within Business Rules, use these sub-headings:

Sub-heading	Purpose
`### Pre-Conditions`	What must be true before the action can happen
`### Post-Conditions`	What happens after processing (success/failure outcomes)
`### Constraints`	Limits, caps, and rules that apply during processing

Within Scenarios, use these patterns:

Sub-heading	Purpose
`### API Scenarios` or `### [Feature] Scenarios`	Standard happy-path and failure scenarios in collapsible tables
`### UI Scenarios`	UI-specific scenarios (when flow differs from API)
`### Edge Cases`	Rare scenarios wrapped in `:::danger Probability`

1. Feature Introduction (H1)

Purpose: Provide a clear, engaging explanation of what the feature does and why it matters.

Keep it concise and business-focused:

What problem does this solve?
Who benefits from it?
When is it used?

Template:

# [Feature Name]

[2-3 sentences explaining the feature's purpose, value, and use case. Focus on the business benefit, not technical implementation.]

Example:

# Split Tender Payments

Split Tender lets a customer divide one checkout total across two saved cards — both charged
together as one coordinated transaction. This gives customers flexibility when a single card
doesn't cover the full amount, while merchants get a single confirmed result.

1b. Get Started Tip

Purpose: Give developers a direct, visible link to the integration guide so they don't have to scroll to Related Documentation.

Place the :::tip Get Started admonition immediately after the H1 intro paragraph, before ## Key Benefits.

Template:

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

Example:

:::tip[Get Started]
To integrate Split Tender Payments, follow the [Integration Guide](/docs/developers/convenient-checkout-api/payments/split-tender/integration) for step-by-step instructions and API details.
:::

2. Key Benefits

Purpose: Immediately show the reader why this feature exists — what problem it solves.

Two components:

Real-world Example — concrete scenario in an :::info callout
Before/After Table — side-by-side comparison of the world without vs. with this feature

Template:

## Key Benefits

:::info[Real-world Example]
[A concrete, relatable scenario showing the feature in action. Use specific dollar amounts and card names.]
:::

| Without [Feature] | With [Feature] |
| ----------------- | -------------- |
| [Problem 1]       | [Solution 1]   |
| [Problem 2]       | [Solution 2]   |
| [Problem 3]       | [Solution 3]   |

Example:

## Key Benefits

:::info[Real-world Example]
A patient owes **$200**. Their health benefits card covers $150; they put the remaining $50
on a personal debit card. Both cards are charged in one session. The merchant gets a single
`COMPLETED` result.
:::

| Without Split Tender                             | With Split Tender                                |
| ------------------------------------------------ | ------------------------------------------------ |
| Card declined for insufficient funds → sale lost | Customer adds a second card and completes inline |
| Merchant must follow up manually                 | One confirmed result with per-card breakdown     |
| Customer starts a separate transaction           | Single checkout confirmation screen              |

3. How It Works

Purpose: Show the reader what happens during processing — outcomes and the happy-path flow.

One components:

Standard Flow Diagram — Mermaid flowchart showing the happy path with styled nodes

Template:

## How It Works

### Standard Flow

[Mermaid flowchart with green/red styling]

Diagram guidance:

Use flowchart LR (left-to-right) for Standard Flows
Use descriptive labels, not "Step 1, Step 2"
Include <code> tags for event names in node labels
Use classDef green for success path, classDef red for failure path
Focus on one clear path per diagram

Example:

### Standard Flow

```mermaid
flowchart LR
    A[Merchant initiates payment
    **PaymentMethodType**: CARD + CARD
    **Payment Type**: SALE]
    B[CCG charges both cards in parallel]
    C{Both authorized?}
    D[Both cards captured]
    E[**PAYMENT_SUCCEEDED** sent to Merchant]
    F[Successful card reversed automatically]
    G[**PAYMENT_FAILED** sent to Merchant]
    
    A --> B --> C
    C -- Yes --> D --> E
    C -- No --> F --> G
    
    classDef green fill:#f1fdf1,stroke:#2ecc40,stroke-width:2px;
    classDef red fill:#fdf1f1,stroke:#e74c3c,stroke-width:2px;
    class A,B,C,D,E green;
    class F,G red;
```

4. Business Rules

Purpose: Define what must be true before, what happens after, and what limits apply.

Always use these three sub-headings:

4.a Pre-Conditions

What must be true before the action can happen. Use a bullet list.

### Pre-Conditions

- [Condition 1]
- [Condition 2]
- [Condition 3]

4.b Post-Conditions

What happens after processing. Use a table with Outcome → Behaviour columns.

### Post-Conditions

| Outcome          | Behaviour      |
| ---------------- | -------------- |
| ✅ [Success case] | [What happens] |
| ❌ [Failure case] | [What happens] |

4.c Constraints

Limits, caps, and rules. Use a table with Constraint → Detail columns.

### Constraints

| Constraint      | Detail        |
| --------------- | ------------- |
| **[Rule name]** | [Explanation] |

Additional sub-sections can be added when the feature has specific rule categories (e.g., "Amount Rules", "Previously Refunded Cards"). Keep them as ### sub-headings under Business Rules.

5. Scenarios

Purpose: Organize scenarios into clear categories that readers can quickly scan.

Use collapsible sections and tables to present scenarios.

5.a Standard Scenarios

## Scenarios

<details open>
<summary>**✅ Standard Scenarios**</summary>

| #   | Scenario       | [Key Columns] | Final Status | Merchant Action |
| --- | -------------- | ------------- | ------------ | --------------- |
| 1   | [Happy path]   | [States]      | ✅ SUCCESS    | None            |
| 2   | [Failure path] | [States]      | ❌ FAILED     | [Action]        |

</details>

5.b Edge Cases

Wrap edge cases in :::danger Probability with recovery strategies:

### Edge Cases

:::danger[Probability]
The probability of these edge cases occurring in production is **low** (< X%).
Most failures are transient and handled by CCG's automatic mechanisms.

<details>
<summary>**Edge Cases**</summary>

| #   | Scenario        | Outcome  | Recovery                    |
| --- | --------------- | -------- | --------------------------- |
| 1   | [Rare scenario] | ❌ FAILED | [Recovery strategy or link] |

</details>
:::

Pro Tips:

Use emojis for visual clarity: ✅ ❌ ⌛ ⚠️ 🚫 🛑
Bold scenario names for emphasis
Use code formatting for status terms: AUTHORIZED, COMPLETED
Keep columns aligned and consistent

6. Notifications

Purpose: Summarize webhook events triggered by the feature.

## Notifications

CCG sends **one webhook per [transaction/request]**:

| Outcome        | Webhook Event | Description         |
| -------------- | ------------- | ------------------- |
| [Success case] | `EVENT_NAME`  | [Brief description] |
| [Failure case] | `EVENT_NAME`  | [Brief description] |

:::caution
Describe any **finality caveats** here — e.g., if a `FAILED` event is not final because retries are still allowed, say so. Business readers (support agents, ops) must know when a failure is truly final before taking action.
:::

note

Keep this as a summary only. Link to developer docs for webhook payload details and handling guidance. For webhook configuration, link to the Webhook Configuration guide.

7. Status Reference

Purpose: Give business, product, and support readers a clear reference for all statuses the feature can produce — what each one means and what action (if any) to take.

When to Include

Include this section when the feature produces statuses that business stakeholders or support agents need to understand and act on — e.g., PENDING, COMPLETED, FAILED, ROLLED_BACK.

What to include:

All possible final and intermediate statuses
A plain-English description of what each status means for the customer/merchant
The recommended action or next step for each status

Template:

## Status Reference

| Status          | Meaning                           | Action                                              |
| --------------- | --------------------------------- | --------------------------------------------------- |
| ✅ `COMPLETED`   | [What it means in business terms] | [e.g., Proceed with fulfilment]                     |
| ❌ `FAILED`      | [What it means]                   | [e.g., Ask customer to retry or use another method] |
| ⏳ `PENDING`     | [What it means]                   | [e.g., Wait for webhook or poll for update]         |
| 🔄 `ROLLED_BACK` | [What it means]                   | [e.g., No charge on this card — retry available]    |

Example:

## Status Reference

| Status          | Meaning                                                                                                | Action                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| ✅ `COMPLETED`   | Both cards were charged successfully. The transaction is complete.                                     | Proceed with order fulfilment.                                      |
| ❌ `FAILED`      | One or both cards could not be charged. No funds were captured.                                        | Ask the customer to retry with different cards.                     |
| ⏳ `PENDING`     | Processing is in progress. The final result is not yet known.                                          | Wait for the `PAYMENT_SUCCEEDED` or `PAYMENT_FAILED` webhook event. |
| 🔄 `ROLLED_BACK` | One card was charged but automatically reversed because the other card failed. No funds were captured. | Inform the customer and offer to retry.                             |

Reference implementation: See Split Tender Payments — Business Guide for a complete Status Reference section.

Purpose: Link to technical docs, related business flows, and API references.

## Related Documentation

- **Technical Integration:** [Link to developer integration doc]
- **Related Business Doc:** [Link to related business use case]
- **API Reference:** [Link to API spec operation]
- **Webhook Reference:** [Link to webhook spec or configuration guide]

Additional Sections (Optional)

warning

Should be followed by Business rules section

These sections can be added when the feature requires them:

Retry & Recovery

When the feature supports retries or rollback:

## Retry & Recovery

| Rule             | Detail                     |
| ---------------- | -------------------------- |
| **When**         | [When retries are allowed] |
| **Max attempts** | [Number]                   |
| **Scope**        | [What gets retried]        |

Cross-References

Link generously to:

Technical API documentation
Recovery strategies
Related business flows
Glossary terms

Documentation Checklist

Before publishing, confirm that the document:

✅ Has a clear, engaging introduction (2–3 sentences)
✅ Has a :::tip Get Started admonition after H1 linking to the integration guide
✅ Has an Key Benefits section with real-world example + before/after table
✅ Has a How It Works section with outcome table + Standard Flow diagram
✅ Uses Pre-Conditions / Post-Conditions / Constraints under Business Rules
✅ Uses tables for scenario comparison (not long prose)
✅ Labels notifications section as Notifications (not "Webhook Summary")
✅ Uses emojis and formatting for visual clarity
✅ Links to related technical/webhook/recovery documentation
✅ Is scannable — readers can skim and find what they need quickly
✅ Focuses on business outcomes, not technical implementation
✅ Internal-only content (processor details, escalation rules) is wrapped in <Audience include="internal">

Technical vs. Business Content

Business docs should answer:

What does this feature do for customers and merchants?
What outcomes can I expect?
When should I use this vs. that?
What happens when things go wrong from a user perspective?

Technical/Developer docs should contain:

System architecture and sequence diagrams
Processing timelines with specific timestamps
API integration details and code examples
Idempotency, retry logic, and error handling
Stripe/payment processor event details

When in doubt: If it helps a product manager, support agent, or business stakeholder understand the feature's impact, it belongs in business docs. If it helps a developer integrate or troubleshoot, it belongs in technical docs.

Standard Section Headings​

Sub-heading Standards​

1. Feature Introduction (H1)​

1b. Get Started Tip​

2. Key Benefits​

3. How It Works​

4. Business Rules​

4.a Pre-Conditions​

4.b Post-Conditions​

4.c Constraints​

5. Scenarios​

5.a Standard Scenarios​

5.b Edge Cases​

6. Notifications​

7. Status Reference​

8. Related Documentation​

Additional Sections (Optional)​

Retry & Recovery​

Cross-References​

Documentation Checklist​

Standard Section Headings

Sub-heading Standards

1. Feature Introduction (H1)

1b. Get Started Tip

2. Key Benefits

3. How It Works

4. Business Rules

4.a Pre-Conditions

4.b Post-Conditions

4.c Constraints

5. Scenarios

5.a Standard Scenarios

5.b Edge Cases

6. Notifications

7. Status Reference

8. Related Documentation

Additional Sections (Optional)

Retry & Recovery

Cross-References

Documentation Checklist