# stripe/stripe-java architecture

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

- Interactive diagram: https://gitdiagram.com/stripe/stripe-java
- Repository: https://github.com/stripe/stripe-java

## Overview

stripe-java is Stripe’s official Java client SDK. An application configures a client and invokes typed service methods; those services turn parameters into API requests, pass them through the response-getter abstraction, and return typed Stripe models or collections. The tree also exposes broad API-domain services and webhook notification handling. Relationships among unsampled service families are kept at subsystem level; the excerpts do not establish their internal routing or the full transport implementation.

Main entry points: [`src/main/java/com/stripe/net/ApiService.java`](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiService.java) (Service base), [`src/main/java/com/stripe/service/checkout/SessionService.java`](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/checkout/SessionService.java) (Checkout sessions), [`src/main/java/com/stripe/net/ApiRequest.java`](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiRequest.java) (API request), [`src/main/java/com/stripe/service/ReviewService.java`](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/ReviewService.java) (Review operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry"]
  node_client["Stripe client<br/>[StripeClient.java]"]
  node_legacy["Legacy API<br/>[Stripe.java]"]
end

subgraph group_services["API services"]
  node_domain_services["Domain services"]
  node_checkout["Checkout sessions"]
  node_checkout_items["Checkout line items"]
  node_reviews["Review operations<br/>[ReviewService.java]"]
  node_identity["Identity verification"]
  node_issuing["Issuing authorizations"]
  node_sigma["Sigma query runs"]
  node_test_helpers["Test helper APIs"]
end

subgraph group_transport["Request and transport"]
  node_params["Typed parameters"]
  node_request["API request<br/>[ApiRequest.java]"]
  node_request_options["Request options"]
  node_api_service["Service base<br/>[ApiService.java]"]
  node_response_getter["Response getter"]
  node_api_resource["Resource utilities<br/>[ApiResource.java]"]
  node_base_address["API addresses<br/>[BaseAddress.java]"]
end

subgraph group_models["Models and events"]
  node_models["Typed models<br/>[StripeObject.java]"]
  node_collections["Paged collections"]
  node_errors["API exceptions"]
  node_webhook_handler["Webhook handlers"]
  node_webhook_events["Event notifications"]
end

node_application(("Java application"))
node_stripe_api(("Stripe API"))

node_application -->|"configures and calls"| node_client
node_application -.->|"may use"| node_legacy
node_checkout -->|"creates"| node_checkout_items
node_checkout -->|"extends"| node_api_service
node_checkout_items -->|"extends"| node_api_service
node_reviews -->|"extends"| node_api_service
node_identity -->|"extends"| node_api_service
node_issuing -->|"extends"| node_api_service
node_sigma -->|"extends"| node_api_service
node_domain_services -.->|"extend service base"| node_api_service
node_test_helpers -.->|"extend service base"| node_api_service
node_checkout -->|"converts parameters"| node_params
node_reviews -->|"converts parameters"| node_params
node_checkout -->|"builds requests"| node_request
node_reviews -->|"builds requests"| node_request
node_request -->|"selects address"| node_base_address
node_request -->|"carries options"| node_request_options
node_api_service -->|"sends request"| node_response_getter
node_response_getter -.->|"makes API call"| node_stripe_api
node_api_service -->|"adds usage metadata"| node_request
node_api_resource -->|"configures serialization"| node_models
node_checkout -->|"returns typed results"| node_models
node_checkout_items -->|"returns paged items"| node_collections
node_reviews -->|"returns paged results"| node_collections
node_response_getter -.->|"reports failures"| node_errors
node_application -.->|"handles notifications"| node_webhook_handler
node_webhook_handler -.->|"dispatches event types"| node_webhook_events

click node_client "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/StripeClient.java"
click node_legacy "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/Stripe.java"
click node_domain_services "https://github.com/stripe/stripe-java/tree/master/src/main/java/com/stripe/service"
click node_checkout "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/checkout/SessionService.java"
click node_checkout_items "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/checkout/SessionLineItemService.java"
click node_reviews "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/ReviewService.java"
click node_identity "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/identity/VerificationSessionService.java"
click node_issuing "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/issuing/AuthorizationService.java"
click node_sigma "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/sigma/ScheduledQueryRunService.java"
click node_test_helpers "https://github.com/stripe/stripe-java/tree/master/src/main/java/com/stripe/service/testhelpers"
click node_params "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiRequestParams.java"
click node_request "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiRequest.java"
click node_request_options "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/RequestOptions.java"
click node_api_service "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiService.java"
click node_response_getter "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/StripeResponseGetter.java"
click node_api_resource "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiResource.java"
click node_base_address "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/BaseAddress.java"
click node_models "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/model/StripeObject.java"
click node_collections "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/model/StripeCollection.java"
click node_errors "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/exception/StripeException.java"
click node_webhook_handler "https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/StripeEventNotificationHandler.java"
click node_webhook_events "https://github.com/stripe/stripe-java/tree/master/src/main/java/com/stripe/events"

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_client,node_legacy toneBlue
class node_domain_services,node_checkout,node_checkout_items,node_reviews,node_identity,node_issuing,node_sigma,node_test_helpers toneAmber
class node_params,node_request,node_request_options,node_api_service,node_response_getter,node_api_resource,node_base_address,node_stripe_api toneMint
class node_models,node_collections,node_errors,node_webhook_handler,node_webhook_events toneRose
class node_application toneIndigo
```

## Components

### Client entry

- [Stripe client](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/StripeClient.java): `src/main/java/com/stripe/StripeClient.java`
- [Legacy API](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/Stripe.java): `src/main/java/com/stripe/Stripe.java`

### API services

- [Domain services](https://github.com/stripe/stripe-java/tree/master/src/main/java/com/stripe/service): `src/main/java/com/stripe/service`
- [Checkout sessions](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/checkout/SessionService.java): `src/main/java/com/stripe/service/checkout/SessionService.java`
- [Checkout line items](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/checkout/SessionLineItemService.java): `src/main/java/com/stripe/service/checkout/SessionLineItemService.java`
- [Review operations](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/ReviewService.java): `src/main/java/com/stripe/service/ReviewService.java`
- [Identity verification](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/identity/VerificationSessionService.java): `src/main/java/com/stripe/service/identity/VerificationSessionService.java`
- [Issuing authorizations](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/issuing/AuthorizationService.java): `src/main/java/com/stripe/service/issuing/AuthorizationService.java`
- [Sigma query runs](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/service/sigma/ScheduledQueryRunService.java): `src/main/java/com/stripe/service/sigma/ScheduledQueryRunService.java`
- [Test helper APIs](https://github.com/stripe/stripe-java/tree/master/src/main/java/com/stripe/service/testhelpers): `src/main/java/com/stripe/service/testhelpers`

### Request and transport

- [Typed parameters](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiRequestParams.java): `src/main/java/com/stripe/net/ApiRequestParams.java`
- [API request](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiRequest.java): `src/main/java/com/stripe/net/ApiRequest.java`
- [Request options](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/RequestOptions.java): `src/main/java/com/stripe/net/RequestOptions.java`
- [Service base](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiService.java): `src/main/java/com/stripe/net/ApiService.java`
- [Response getter](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/StripeResponseGetter.java): `src/main/java/com/stripe/net/StripeResponseGetter.java`
- [Resource utilities](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/ApiResource.java): `src/main/java/com/stripe/net/ApiResource.java`
- [API addresses](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/net/BaseAddress.java): `src/main/java/com/stripe/net/BaseAddress.java`

### Models and events

- [Typed models](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/model/StripeObject.java): `src/main/java/com/stripe/model/StripeObject.java`
- [Paged collections](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/model/StripeCollection.java): `src/main/java/com/stripe/model/StripeCollection.java`
- [API exceptions](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/exception/StripeException.java): `src/main/java/com/stripe/exception/StripeException.java`
- [Webhook handlers](https://github.com/stripe/stripe-java/blob/master/src/main/java/com/stripe/StripeEventNotificationHandler.java): `src/main/java/com/stripe/StripeEventNotificationHandler.java`
- [Event notifications](https://github.com/stripe/stripe-java/tree/master/src/main/java/com/stripe/events): `src/main/java/com/stripe/events`

### Other components

- **Java application**
- **Stripe API**

## Connections

- Java application → Stripe client: configures and calls (evidence: `README.md`)
- Java application → Legacy API: may use (evidence: `README.md`)
- Checkout sessions → Checkout line items: creates (evidence: `src/main/java/com/stripe/service/checkout/SessionService.java`)
- Checkout sessions → Service base: extends (evidence: `src/main/java/com/stripe/service/checkout/SessionService.java`)
- Checkout line items → Service base: extends (evidence: `src/main/java/com/stripe/service/checkout/SessionLineItemService.java`)
- Review operations → Service base: extends (evidence: `src/main/java/com/stripe/service/ReviewService.java`)
- Identity verification → Service base: extends (evidence: `src/main/java/com/stripe/service/identity/VerificationSessionService.java`)
- Issuing authorizations → Service base: extends (evidence: `src/main/java/com/stripe/service/issuing/AuthorizationService.java`)
- Sigma query runs → Service base: extends (evidence: `src/main/java/com/stripe/service/sigma/ScheduledQueryRunService.java`)
- Domain services → Service base: extend service base (evidence: `src/main/java/com/stripe/service/sigma/ScheduledQueryRunService.java`)
- Test helper APIs → Service base: extend service base (evidence: `src/main/java/com/stripe/service/testhelpers/issuing/AuthorizationService.java`)
- Checkout sessions → Typed parameters: converts parameters (evidence: `src/main/java/com/stripe/service/checkout/SessionService.java`)
- Review operations → Typed parameters: converts parameters (evidence: `src/main/java/com/stripe/service/ReviewService.java`)
- Checkout sessions → API request: builds requests (evidence: `src/main/java/com/stripe/service/checkout/SessionService.java`)
- Review operations → API request: builds requests (evidence: `src/main/java/com/stripe/service/ReviewService.java`)
- API request → API addresses: selects address (evidence: `src/main/java/com/stripe/service/checkout/SessionService.java`)
- API request → Request options: carries options (evidence: `src/main/java/com/stripe/service/checkout/SessionService.java`)
- Service base → Response getter: sends request (evidence: `src/main/java/com/stripe/net/ApiService.java`)
- Response getter → Stripe API: makes API call
- Service base → API request: adds usage metadata (evidence: `src/main/java/com/stripe/net/ApiService.java`)
- Resource utilities → Typed models: configures serialization (evidence: `src/main/java/com/stripe/net/ApiResource.java`)
- Checkout sessions → Typed models: returns typed results (evidence: `src/main/java/com/stripe/service/checkout/SessionService.java`)
- Checkout line items → Paged collections: returns paged items (evidence: `src/main/java/com/stripe/service/checkout/SessionLineItemService.java`)
- Review operations → Paged collections: returns paged results (evidence: `src/main/java/com/stripe/service/ReviewService.java`)
- Response getter → API exceptions: reports failures (evidence: `src/main/java/com/stripe/net/StripeResponseGetter.java`)
- Java application → Webhook handlers: handles notifications
- Webhook handlers → Event notifications: dispatches event types
