How cybersource/cybersource-unified-checkout-sample-dotnet works
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: Checkout.cshtml Checkout view · HomeController.cs HomeController · SessionsService.cs SessionsService · CaptureContextValidator.cs JWT validator
Components 15
ASP.NET Core app
Server-side MVC app that creates and validates checkout sessions
- Program.cs · Configures ASP.NET Core host, MVC, static files, and routing
Program.cs - HomeController · Single controller for checkout page flow and payment response handling
Controllers/HomeController.cs - SessionsService · Creates Unified Checkout sessions via CyberSource HTTP Signature request
SessionsService.cs - JWT validator · Validates capture-context JWT signatures before claims are trusted
CaptureContextValidator.cs - CyberSource config · Merchant credentials, key material, and target API environment
CyberSourceConfiguration.cs - Session request · 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 · Main checkout page that loads the hosted JS library and mounts the widget
Views/Home/Checkout.cshtml - Complete view · Displays the posted payment response JWT after checkout completion
Views/Home/CompletePaymentResponse.cshtml - site.js · Local browser behavior supporting the checkout page
wwwroot/js/site.js - site.css · App-specific styling for the Razor views
wwwroot/css/site.css - Vendor libs · Bundled jQuery and Bootstrap assets for the sample UI
wwwroot/lib
CyberSource
External CyberSource APIs and hosted assets
- Sessions API · CyberSource POST /uc/v1/sessions endpoint that returns the capture-context JWT
- Public key · CyberSource public key endpoint used to verify the session JWT
- SecureAcceptance.js · CyberSource-hosted browser library loaded by the checkout page
- Unified Checkout · Hosted payment UI initialized in the browser with the session JWT
Connections 15
- 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