# intuit/quickbooks-v3-java-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/intuit/quickbooks-v3-java-sdk
- Repository: https://github.com/intuit/quickbooks-v3-java-sdk

## Overview

This repository is a Java SDK for QuickBooks Online, with separate OAuth2 and Payments V2 client libraries. A typical QBO integration calls the devkit’s data or reporting services, which exchange entity or report data with QuickBooks Online; the data module supplies the API’s entity models. The README documents CRUD, batch operations, queries, change-data retrieval, XML/JSON, synchronous/asynchronous handling, and resilience features. Service internals are only partly sampled, so the graph avoids asserting unshown call chains.

Main entry points: [`ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/DataService.java`](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/DataService.java) (Data Service), [`payments-api/src/main/java/com/intuit/payment/services/base/ServiceBase.java`](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/base/ServiceBase.java) (Payment Transport), [`oauth2-platform-api/src/main/java/com/intuit/oauth2/client/OAuth2PlatformClient.java`](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/oauth2-platform-api/src/main/java/com/intuit/oauth2/client/OAuth2PlatformClient.java) (OAuth2 Client), [`ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/ReportService.java`](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/ReportService.java) (Report Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["QBO Data Models"]
  node_entity_base["Entity Base<br/>[IntuitEntity.java]"]
  node_entity_records["Business Entities<br/>[Invoice.java]"]
  node_query_results["Query Responses<br/>[QueryResponse.java]"]
  node_faults["API Faults<br/>[Fault.java]"]
  node_tax_models["Tax Models<br/>[TaxService.java]"]
end

subgraph group_devkit["QBO API Devkit"]
  node_data_service["Data Service<br/>[DataService.java]"]
  node_report_service["Report Service<br/>[ReportService.java]"]
  node_tax_service["Tax Service"]
  node_webhook_service["Webhook Service"]
  node_request_interceptor["HTTP Interceptors"]
  node_batch_interceptor["Batch Interceptor"]
  node_retry_policy["Retry Policy"]
end

subgraph group_oauth["OAuth2 Client"]
  node_oauth_client["OAuth2 Client"]
  node_oauth_config["OAuth Configuration<br/>[OAuth2Config.java]"]
  node_oauth_http["OAuth HTTP Client"]
end

subgraph group_payments["Payments V2"]
  node_payments_context["Payment Context"]
  node_bank_service["Bank Accounts"]
  node_card_service["Card Service<br/>[CardService.java]"]
  node_charge_service["Charge Service<br/>[ChargeService.java]"]
  node_payment_base["Payment Transport<br/>[ServiceBase.java]"]
  node_payment_http["Payment HTTP Client"]
end

node_developer(("SDK Consumer"))
node_qbo[("QuickBooks Online")]
node_payment_api[("Payments API")]

node_developer -->|"invokes CRUD"| node_data_service
node_developer -->|"requests reports"| node_report_service
node_data_service -->|"sends API requests"| node_qbo
node_report_service -->|"retrieves reports"| node_qbo
node_data_service -->|"handles entities"| node_entity_records
node_data_service -->|"processes queries"| node_query_results
node_data_service -->|"handles faults"| node_faults
node_developer -->|"requests tax"| node_tax_service
node_tax_service -.->|"uses tax model"| node_tax_models
node_developer -->|"uses webhooks"| node_webhook_service
node_developer -->|"requests tokens"| node_oauth_client
node_oauth_client -->|"uses configuration"| node_oauth_config
node_oauth_client -->|"makes HTTP calls"| node_oauth_http
node_developer -->|"manages accounts"| node_bank_service
node_developer -->|"manages cards"| node_card_service
node_developer -->|"processes charges"| node_charge_service
node_bank_service -->|"sends requests"| node_payment_base
node_card_service -.->|"sends requests"| node_payment_base
node_charge_service -.->|"sends requests"| node_payment_base
node_payment_base -->|"makes API call"| node_payment_http
node_payment_http -->|"calls payment API"| node_payment_api

click node_data_service "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/DataService.java"
click node_report_service "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/ReportService.java"
click node_tax_service "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/GlobalTaxService.java"
click node_webhook_service "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/WebhooksService.java"
click node_request_interceptor "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/interceptors/HTTPClientConnectionInterceptor.java"
click node_batch_interceptor "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/interceptors/HTTPBatchClientConnectionInterceptor.java"
click node_retry_policy "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/net/IntuitRetryPolicyHandler.java"
click node_entity_base "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/IntuitEntity.java"
click node_entity_records "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/Invoice.java"
click node_query_results "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/QueryResponse.java"
click node_faults "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/Fault.java"
click node_tax_models "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/TaxService.java"
click node_oauth_client "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/oauth2-platform-api/src/main/java/com/intuit/oauth2/client/OAuth2PlatformClient.java"
click node_oauth_config "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/oauth2-platform-api/src/main/java/com/intuit/oauth2/config/OAuth2Config.java"
click node_oauth_http "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/oauth2-platform-api/src/main/java/com/intuit/oauth2/http/HttpRequestClient.java"
click node_payments_context "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/config/RequestContext.java"
click node_bank_service "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/BankAccountService.java"
click node_card_service "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/CardService.java"
click node_charge_service "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/ChargeService.java"
click node_payment_base "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/base/ServiceBase.java"
click node_payment_http "https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/http/HttpRequestClient.java"

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_entity_base,node_entity_records,node_query_results,node_faults,node_tax_models toneBlue
class node_data_service,node_report_service,node_tax_service,node_webhook_service,node_request_interceptor,node_batch_interceptor,node_retry_policy,node_qbo,node_payment_api toneAmber
class node_oauth_client,node_oauth_config,node_oauth_http toneMint
class node_payments_context,node_bank_service,node_card_service,node_charge_service,node_payment_base,node_payment_http toneRose
class node_developer toneIndigo
```

## Components

### QBO Data Models

- [Entity Base](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/IntuitEntity.java): `ipp-v3-java-data/src/main/java/com/intuit/ipp/data/IntuitEntity.java`
- [Business Entities](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/Invoice.java): `ipp-v3-java-data/src/main/java/com/intuit/ipp/data/Invoice.java`
- [Query Responses](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/QueryResponse.java): `ipp-v3-java-data/src/main/java/com/intuit/ipp/data/QueryResponse.java`
- [API Faults](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/Fault.java): `ipp-v3-java-data/src/main/java/com/intuit/ipp/data/Fault.java`
- [Tax Models](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-data/src/main/java/com/intuit/ipp/data/TaxService.java): `ipp-v3-java-data/src/main/java/com/intuit/ipp/data/TaxService.java`

### QBO API Devkit

- [Data Service](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/DataService.java): `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/DataService.java`
- [Report Service](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/ReportService.java): `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/ReportService.java`
- [Tax Service](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/GlobalTaxService.java): `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/GlobalTaxService.java`
- [Webhook Service](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/WebhooksService.java): `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/WebhooksService.java`
- [HTTP Interceptors](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/interceptors/HTTPClientConnectionInterceptor.java): `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/interceptors/HTTPClientConnectionInterceptor.java`
- [Batch Interceptor](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/interceptors/HTTPBatchClientConnectionInterceptor.java): `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/interceptors/HTTPBatchClientConnectionInterceptor.java`
- [Retry Policy](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/ipp-v3-java-devkit/src/main/java/com/intuit/ipp/net/IntuitRetryPolicyHandler.java): `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/net/IntuitRetryPolicyHandler.java`

### OAuth2 Client

- [OAuth2 Client](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/oauth2-platform-api/src/main/java/com/intuit/oauth2/client/OAuth2PlatformClient.java): `oauth2-platform-api/src/main/java/com/intuit/oauth2/client/OAuth2PlatformClient.java`
- [OAuth Configuration](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/oauth2-platform-api/src/main/java/com/intuit/oauth2/config/OAuth2Config.java): `oauth2-platform-api/src/main/java/com/intuit/oauth2/config/OAuth2Config.java`
- [OAuth HTTP Client](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/oauth2-platform-api/src/main/java/com/intuit/oauth2/http/HttpRequestClient.java): `oauth2-platform-api/src/main/java/com/intuit/oauth2/http/HttpRequestClient.java`

### Payments V2

- [Payment Context](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/config/RequestContext.java): `payments-api/src/main/java/com/intuit/payment/config/RequestContext.java`
- [Bank Accounts](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/BankAccountService.java): `payments-api/src/main/java/com/intuit/payment/services/BankAccountService.java`
- [Card Service](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/CardService.java): `payments-api/src/main/java/com/intuit/payment/services/CardService.java`
- [Charge Service](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/ChargeService.java): `payments-api/src/main/java/com/intuit/payment/services/ChargeService.java`
- [Payment Transport](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/services/base/ServiceBase.java): `payments-api/src/main/java/com/intuit/payment/services/base/ServiceBase.java`
- [Payment HTTP Client](https://github.com/intuit/quickbooks-v3-java-sdk/blob/develop/payments-api/src/main/java/com/intuit/payment/http/HttpRequestClient.java): `payments-api/src/main/java/com/intuit/payment/http/HttpRequestClient.java`

### Other components

- **SDK Consumer**
- **QuickBooks Online**
- **Payments API**

## Connections

- SDK Consumer → Data Service: invokes CRUD
- SDK Consumer → Report Service: requests reports
- Data Service → QuickBooks Online: sends API requests
- Report Service → QuickBooks Online: retrieves reports
- Data Service → Business Entities: handles entities (evidence: `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/DataService.java`)
- Data Service → Query Responses: processes queries (evidence: `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/DataService.java`)
- Data Service → API Faults: handles faults (evidence: `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/DataService.java`)
- SDK Consumer → Tax Service: requests tax
- Tax Service → Tax Models: uses tax model (evidence: `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/GlobalTaxService.java`)
- SDK Consumer → Webhook Service: uses webhooks (evidence: `ipp-v3-java-devkit/src/main/java/com/intuit/ipp/services/WebhooksService.java`)
- SDK Consumer → OAuth2 Client: requests tokens
- OAuth2 Client → OAuth Configuration: uses configuration (evidence: `oauth2-platform-api/src/main/java/com/intuit/oauth2/client/OAuth2PlatformClient.java`)
- OAuth2 Client → OAuth HTTP Client: makes HTTP calls (evidence: `oauth2-platform-api/src/main/java/com/intuit/oauth2/client/OAuth2PlatformClient.java`)
- SDK Consumer → Bank Accounts: manages accounts
- SDK Consumer → Card Service: manages cards
- SDK Consumer → Charge Service: processes charges
- Bank Accounts → Payment Transport: sends requests (evidence: `payments-api/src/main/java/com/intuit/payment/services/BankAccountService.java`)
- Card Service → Payment Transport: sends requests (evidence: `payments-api/src/main/java/com/intuit/payment/services/CardService.java`)
- Charge Service → Payment Transport: sends requests (evidence: `payments-api/src/main/java/com/intuit/payment/services/ChargeService.java`)
- Payment Transport → Payment HTTP Client: makes API call (evidence: `payments-api/src/main/java/com/intuit/payment/services/base/ServiceBase.java`)
- Payment HTTP Client → Payments API: calls payment API
