# cybersource/cybersource-plugins-commercetools architecture

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

- Interactive diagram: https://gitdiagram.com/cybersource/cybersource-plugins-commercetools
- Repository: https://github.com/cybersource/cybersource-plugins-commercetools

## Overview

This is a Commercetools HTTP API Extension that mediates payment operations between Commercetools and Cybersource. The main flow is an API-extension request, payment-method handling and request preparation, a Cybersource operation, then a synchronous response to Commercetools; order creation remains front-end business logic. The README also documents tokenization, capture, refund, authorization reversal, payment synchronization, and network-token webhooks. The sampled source confirms authorization request construction and payer-authentication setup; other subsystem links reflect documented capabilities and module names, not inspected call sites.

Main entry points: [`src/apiController.ts`](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/apiController.ts) (Payment controller), [`src/utils/PaymentHandler.ts`](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/utils/PaymentHandler.ts) (Payment actions), [`src/requestBuilder/PrepareFields.ts`](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/requestBuilder/PrepareFields.ts) (Request preparation), [`src/service/payment/PaymentAuthorizationService.ts`](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PaymentAuthorizationService.ts) (Authorization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension runtime"]
  node_entry["Extension entry<br/>[index.ts]"]
  node_router["Request routing<br/>[RouterHandler.ts]"]
  node_app["Application handler<br/>[AppHandler.ts]"]
  node_response["Extension response<br/>[apiController.ts]"]
end

subgraph group_payment["Payment processing"]
  node_controller["Payment controller<br/>[apiController.ts]"]
  node_handler["Payment actions<br/>[PaymentHandler.ts]"]
  node_methods["Payment methods"]
  node_methodstrategies["Method strategies"]
  node_requestprep["Request preparation<br/>[PrepareFields.ts]"]
  node_authorization["Authorization"]
  node_payerauth["Payer authentication"]
end

subgraph group_integrations["Platform integrations"]
  node_ctapi["Commercetools API"]
  node_cybersource["Cybersource API<br/>[IsvApi.ts]"]
end

subgraph group_lifecycle["Payment lifecycle"]
  node_tokenops["Token management<br/>[AddTokenService.ts]"]
  node_webhooks["Webhook subscriptions"]
  node_sync["Payment synchronization"]
  node_capture["Capture and refund"]
  node_reversal["Authorization reversal"]
end

node_frontend(("Storefront"))
node_ct(("Commercetools"))

node_frontend -->|"submits payment"| node_ct
node_ct -->|"invokes extension"| node_entry
node_entry -->|"dispatches request"| node_router
node_router -->|"routes request"| node_app
node_app -->|"handles payment"| node_controller
node_controller -->|"dispatches actions"| node_handler
node_handler -->|"selects method"| node_methods
node_methods -->|"resolves strategy"| node_methodstrategies
node_handler -->|"prepares request"| node_requestprep
node_authorization -->|"builds fields"| node_requestprep
node_authorization -->|"submits authorization"| node_cybersource
node_payerauth -->|"builds setup request"| node_requestprep
node_payerauth -->|"starts authentication"| node_cybersource
node_controller -->|"uses platform API"| node_ctapi
node_controller -->|"manages tokens"| node_tokenops
node_controller -->|"manages subscriptions"| node_webhooks
node_controller -->|"synchronizes payments"| node_sync
node_controller -->|"captures or refunds"| node_capture
node_controller -->|"reverses authorization"| node_reversal
node_controller -->|"returns result"| node_response
node_response -->|"responds synchronously"| node_ct

click node_entry "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/index.ts"
click node_router "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/app/RouterHandler.ts"
click node_app "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/app/AppHandler.ts"
click node_controller "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/apiController.ts"
click node_handler "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/utils/PaymentHandler.ts"
click node_methods "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/models/PaymentMethodFactory.ts"
click node_methodstrategies "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/models/PaymentMethodStrategy.ts"
click node_requestprep "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/requestBuilder/PrepareFields.ts"
click node_authorization "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PaymentAuthorizationService.ts"
click node_payerauth "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PayerAuthenticationSetupService.ts"
click node_ctapi "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/utils/api/CommercetoolsApi.ts"
click node_cybersource "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/utils/api/IsvApi.ts"
click node_tokenops "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/AddTokenService.ts"
click node_webhooks "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/CreateWebhookSubscription.ts"
click node_sync "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/DecisionSyncService.ts"
click node_capture "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PaymentCaptureService.ts"
click node_reversal "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PaymentAuthorizationReversal.ts"
click node_response "https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/apiController.ts"

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_entry,node_router,node_app,node_response toneBlue
class node_controller,node_handler,node_methods,node_methodstrategies,node_requestprep,node_authorization,node_payerauth toneAmber
class node_ctapi,node_cybersource toneMint
class node_tokenops,node_webhooks,node_sync,node_capture,node_reversal toneRose
class node_frontend,node_ct toneIndigo
```

## Components

### Extension runtime

- [Extension entry](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/index.ts): `src/index.ts`
- [Request routing](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/app/RouterHandler.ts): `src/app/RouterHandler.ts`
- [Application handler](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/app/AppHandler.ts): `src/app/AppHandler.ts`
- [Extension response](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/apiController.ts): `src/apiController.ts`

### Payment processing

- [Payment controller](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/apiController.ts): `src/apiController.ts`
- [Payment actions](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/utils/PaymentHandler.ts): `src/utils/PaymentHandler.ts`
- [Payment methods](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/models/PaymentMethodFactory.ts): `src/models/PaymentMethodFactory.ts`
- [Method strategies](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/models/PaymentMethodStrategy.ts): `src/models/PaymentMethodStrategy.ts`
- [Request preparation](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/requestBuilder/PrepareFields.ts): `src/requestBuilder/PrepareFields.ts`
- [Authorization](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PaymentAuthorizationService.ts): `src/service/payment/PaymentAuthorizationService.ts`
- [Payer authentication](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PayerAuthenticationSetupService.ts): `src/service/payment/PayerAuthenticationSetupService.ts`

### Platform integrations

- [Commercetools API](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/utils/api/CommercetoolsApi.ts): `src/utils/api/CommercetoolsApi.ts`
- [Cybersource API](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/utils/api/IsvApi.ts): `src/utils/api/IsvApi.ts`

### Payment lifecycle

- [Token management](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/AddTokenService.ts): `src/service/payment/AddTokenService.ts`
- [Webhook subscriptions](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/CreateWebhookSubscription.ts): `src/service/payment/CreateWebhookSubscription.ts`
- [Payment synchronization](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/DecisionSyncService.ts): `src/service/payment/DecisionSyncService.ts`
- [Capture and refund](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PaymentCaptureService.ts): `src/service/payment/PaymentCaptureService.ts`
- [Authorization reversal](https://github.com/cybersource/cybersource-plugins-commercetools/blob/master/src/service/payment/PaymentAuthorizationReversal.ts): `src/service/payment/PaymentAuthorizationReversal.ts`

### Other components

- **Storefront**
- **Commercetools**

## Connections

- Storefront → Commercetools: submits payment
- Commercetools → Extension entry: invokes extension
- Extension entry → Request routing: dispatches request
- Request routing → Application handler: routes request
- Application handler → Payment controller: handles payment
- Payment controller → Payment actions: dispatches actions
- Payment actions → Payment methods: selects method
- Payment methods → Method strategies: resolves strategy
- Payment actions → Request preparation: prepares request
- Authorization → Request preparation: builds fields
- Authorization → Cybersource API: submits authorization
- Payer authentication → Request preparation: builds setup request
- Payer authentication → Cybersource API: starts authentication
- Payment controller → Commercetools API: uses platform API
- Payment controller → Token management: manages tokens
- Payment controller → Webhook subscriptions: manages subscriptions
- Payment controller → Payment synchronization: synchronizes payments
- Payment controller → Capture and refund: captures or refunds
- Payment controller → Authorization reversal: reverses authorization
- Payment controller → Extension response: returns result
- Extension response → Commercetools: responds synchronously