# cybersource/cybersource-unified-checkout-sample-dotnet architecture

> Architecture diagram of the GitHub repository cybersource/cybersource-unified-checkout-sample-dotnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cybersource/cybersource-unified-checkout-sample-dotnet
- Repository: https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet

## Overview

1. **System shape**
   - This is a minimal **ASP.NET Core 8 MVC** sample for **CyberSource Unified Checkout**.
   - It has one server-side web app, one browser-based checkout widget, and two CyberSource API touchpoints. There is **no database, queue, or background worker**.

2. **Primary boundary: browser vs server**
   - The **server** is responsible for getting a checkout session from CyberSource, validating the returned JWT, and rendering the page.
   - The **browser** is responsible for loading the CyberSource-hosted JavaScript checkout library, mounting the payment UI, and later posting the completed payment response back to the server.

3. **Server entry point and routing**
   - `Program.cs` sets up the ASP.NET Core host, MVC, static files, and the route mapping.
   - `Controllers/HomeController.cs` is the only controller and provides the checkout page flow plus the post-payment response handling.
   - The app appears intentionally routed around a single checkout experience rather than a general-purpose site.

4. **Configuration subsystem**
   - `CyberSourceConfiguration.cs` holds the merchant credentials and target environment, including the CyberSource merchant ID, key ID, secret key, and API host.
   - `CaptureContextRequest.cs` defines the session request parameters that shape checkout behavior, such as target origin, country, locale, amount, and currency.
   - `CaptureContextValidator.cs` supports trust establishment by verifying the session JWT before the app uses its claims.

5. **Checkout session acquisition**
   - `SessionsService.cs` is the server’s integration client for CyberSource.
   - It performs the authenticated `POST /uc/v1/sessions` request using **HTTP Signature authentication** and receives the signed capture-context JWT used to initialize Unified Checkout.
   - This service is the main outbound API boundary from the app to CyberSource.

6. **JWT trust and public-key validation**
   - Before the app trusts data from the session token, `CaptureContextValidator.cs` fetches CyberSource’s public key and validates the JWT signature with **RS256**.
   - That validation step is architecturally important: it separates “received from external API” from “safe to consume in the app.”
   - The validated claims provide the `clientLibrary` URL and the `clientLibraryIntegrity` value passed to the checkout view.

7. **Checkout rendering and client-side payment widget**
   - `Views/Home/Checkout.cshtml` is the main UI surface.
   - It loads the CyberSource `SecureAcceptance.js` library from the validated client library URL, using the integrity hash to enforce browser-side Subresource Integrity.
   - Once loaded, the browser initializes `VAS.UnifiedCheckout(sessionJWT)`, creates the checkout widget, and mounts it into the page DOM.

8. **Payment completion callback path**
   - After the shopper finishes the payment flow, the browser receives a payment result JWT from the widget.
   - That token is posted back to the app and rendered by `Views/Home/CompletePaymentResponse.cshtml`.
   - This is a display-only endpoint in the sample; it does not persist orders or perform fulfillment.

9. **Data flow summary**
   - Browser requests checkout page.
   - Server requests session from CyberSource.
   - Server validates session JWT signature and extracts trusted values.
   - Browser loads the CyberSource checkout JS using those values.
   - Shopper completes payment in the hosted widget.
   - Browser posts the result JWT back to the server for decoding/display.

10. **Important external dependencies and service boundaries**
   - The app depends on **CyberSource’s Unified Checkout and Flex APIs** for session creation, public-key retrieval, and payment processing.
   - It also depends on the **CyberSource-hosted JavaScript library** delivered to the browser.
   - Because the sample has no persistence or production hardening, the architecture is best understood as a thin orchestration layer around CyberSource, not as a full commerce backend.

11. **UI and static assets**
   - `wwwroot` contains standard static assets: CSS, JavaScript, and vendored front-end libraries such as jQuery and Bootstrap.
   - These assets support the Razor views but are not core business logic; the real integration center is the checkout widget loaded from CyberSource.

12. **Operational constraints**
   - The capture-context origin must match the local URL used in the browser, or the widget will not initialize.
   - The README notes that the sample targets CyberSource test infrastructure and uses local development HTTPS profiles.
   - This sample is intentionally minimal and should be treated as an integration reference, not a production payment platform.

Main entry points: [`Views/Home/Checkout.cshtml`](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Views/Home/Checkout.cshtml) (Checkout view), [`Controllers/HomeController.cs`](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Controllers/HomeController.cs) (HomeController), [`SessionsService.cs`](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/SessionsService.cs) (SessionsService), [`CaptureContextValidator.cs`](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/CaptureContextValidator.cs) (JWT validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["ASP.NET Core app"]
  node_program["Program.cs<br/>host setup<br/>[Program.cs]"]
  node_home_controller["HomeController<br/>MVC controller<br/>[HomeController.cs]"]
  node_sessions_service["SessionsService<br/>API client<br/>[SessionsService.cs]"]
  node_capture_validator["JWT validator<br/>security"]
  node_cybersource_config["CyberSource config<br/>settings"]
  node_capture_request["Session request<br/>request model"]
end

subgraph group_client["Browser checkout"]
  node_checkout_view["Checkout view<br/>Razor page<br/>[Checkout.cshtml]"]
  node_complete_view["Complete view<br/>Razor page"]
  node_site_js["site.js<br/>browser script<br/>[site.js]"]
  node_site_css["site.css<br/>styles<br/>[site.css]"]
  node_vendor_libs["Vendor libs<br/>static assets"]
end

subgraph group_external["CyberSource"]
  node_cybersource_sessions_api[("Sessions API<br/>Unified Checkout API")]
  node_cybersource_public_key["Public key<br/>CyberSource key"]
  node_hosted_checkout_js["SecureAcceptance.js<br/>hosted library"]
  node_unified_widget["Unified Checkout<br/>browser widget"]
end

node_program -->|"routes to"| node_home_controller
node_home_controller -->|"creates session"| node_sessions_service
node_home_controller -->|"validates token"| node_capture_validator
node_sessions_service -->|"uses creds"| node_cybersource_config
node_sessions_service -->|"builds from"| node_capture_request
node_sessions_service -->|"POST /uc/v1/sessions"| node_cybersource_sessions_api
node_capture_validator -->|"fetches key"| node_cybersource_public_key
node_capture_validator -->|"provides claims"| node_checkout_view
node_checkout_view -->|"loads"| node_hosted_checkout_js
node_checkout_view -->|"initializes"| node_unified_widget
node_checkout_view -->|"uses"| node_site_js
node_checkout_view -->|"styles with"| node_site_css
node_checkout_view -->|"depends on"| node_vendor_libs
node_unified_widget -->|"posts result"| node_complete_view
node_home_controller -->|"renders"| node_complete_view

click node_program "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Program.cs"
click node_home_controller "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Controllers/HomeController.cs"
click node_sessions_service "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/SessionsService.cs"
click node_capture_validator "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/CaptureContextValidator.cs"
click node_cybersource_config "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/CyberSourceConfiguration.cs"
click node_capture_request "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/CaptureContextRequest.cs"
click node_checkout_view "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Views/Home/Checkout.cshtml"
click node_complete_view "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Views/Home/CompletePaymentResponse.cshtml"
click node_site_js "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/wwwroot/js/site.js"
click node_site_css "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/wwwroot/css/site.css"
click node_vendor_libs "https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/tree/main/wwwroot/lib"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_program,node_home_controller,node_sessions_service,node_capture_validator,node_cybersource_config,node_capture_request toneBlue
class node_checkout_view,node_complete_view,node_site_js,node_site_css,node_vendor_libs toneAmber
class node_cybersource_sessions_api,node_cybersource_public_key,node_hosted_checkout_js,node_unified_widget toneMint
```

## Components

### ASP.NET Core app

Server-side MVC app that creates and validates checkout sessions

- [Program.cs](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Program.cs): host setup · Configures ASP.NET Core host, MVC, static files, and routing · `Program.cs`
- [HomeController](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Controllers/HomeController.cs): MVC controller · Single controller for checkout page flow and payment response handling · `Controllers/HomeController.cs`
- [SessionsService](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/SessionsService.cs): API client · Creates Unified Checkout sessions via CyberSource HTTP Signature request · `SessionsService.cs`
- [JWT validator](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/CaptureContextValidator.cs): security · Validates capture-context JWT signatures before claims are trusted · `CaptureContextValidator.cs`
- [CyberSource config](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/CyberSourceConfiguration.cs): settings · Merchant credentials, key material, and target API environment · `CyberSourceConfiguration.cs`
- [Session request](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/CaptureContextRequest.cs): request model · Defines target origin, locale, country, amount, and currency for checkout · `CaptureContextRequest.cs`

### Browser checkout

Client-side page and widget that render and complete payment

- [Checkout view](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Views/Home/Checkout.cshtml): Razor page · Main checkout page that loads the hosted JS library and mounts the widget · `Views/Home/Checkout.cshtml`
- [Complete view](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/Views/Home/CompletePaymentResponse.cshtml): Razor page · Displays the posted payment response JWT after checkout completion · `Views/Home/CompletePaymentResponse.cshtml`
- [site.js](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/wwwroot/js/site.js): browser script · Local browser behavior supporting the checkout page · `wwwroot/js/site.js`
- [site.css](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/blob/main/wwwroot/css/site.css): styles · App-specific styling for the Razor views · `wwwroot/css/site.css`
- [Vendor libs](https://github.com/cybersource/cybersource-unified-checkout-sample-dotnet/tree/main/wwwroot/lib): static assets · Bundled jQuery and Bootstrap assets for the sample UI · `wwwroot/lib`

### CyberSource

External CyberSource APIs and hosted assets

- **Sessions API**: Unified Checkout API · CyberSource POST /uc/v1/sessions endpoint that returns the capture-context JWT
- **Public key**: CyberSource key · CyberSource public key endpoint used to verify the session JWT
- **SecureAcceptance.js**: hosted library · CyberSource-hosted browser library loaded by the checkout page
- **Unified Checkout**: browser widget · Hosted payment UI initialized in the browser with the session JWT

## Connections

- Program.cs → HomeController: routes to · Maps the single checkout experience to the controller
- HomeController → SessionsService: creates session · Requests capture context before rendering checkout
- HomeController → JWT validator: validates token · Checks the session JWT before trusting its claims
- SessionsService → CyberSource config: uses creds · Reads merchant ID, key ID, secret, and API host
- SessionsService → Session request: builds from · Shapes the checkout session request payload
- SessionsService → Sessions API: POST /uc/v1/sessions · Authenticated outbound API call to CyberSource
- JWT validator → Public key: fetches key · Retrieves CyberSource public key for RS256 verification
- JWT validator → Checkout view: provides claims · Supplies client library URL and integrity hash to the page
- Checkout view → SecureAcceptance.js: loads · Browser loads the CyberSource-hosted checkout library
- Checkout view → Unified Checkout: initializes · Creates VAS.UnifiedCheckout(sessionJWT) and mounts the UI
- Checkout view → site.js: uses · Supports local page behavior
- Checkout view → site.css: styles with · Applies app styling
- Checkout view → Vendor libs: depends on · Uses bundled front-end libraries
- Unified Checkout → Complete view: posts result · Sends the payment response JWT back to the app
- HomeController → Complete view: renders · Displays the returned payment response for the sample