Release 8.7.0 (#688)

This release introduces support for the Cash App Pay payment method and enhances customer and device data models to support new payment flows and risk checks. The most important changes are summarized below:

**Cash App Pay Integration:**

* Added the `CashApp` payment method, including its configuration, initialization state, customer profile sharing, and next action handling, to `PaymentMethods` and as a new class with supporting entities (`CashAppAction`, `CashAppActionType`, `CashAppCustomerProfile`, `CashAppAddress`). [[1]](diffhunk://#diff-286d0d3e749765f2f48d58470ae95d4d47a3c6fe1ae88d0bc4f2e956f1dad640R1-R53) [[2]](diffhunk://#diff-0203bfce00a106da0ae75f034eedc1a3cb0e0fba543da1b206f8b85936c9a6d5R1-R30) [[3]](diffhunk://#diff-0fd48b43e8088468d37795fbcab5534cca3c8e7a7e77b2cef089e168cb574cb2R1-R15) [[4]](diffhunk://#diff-4219cc39e8d2f044c852a22fe2b148c0352483e41d6d8076414de9c44dfdd9aaR1-R102) [[5]](diffhunk://#diff-8f81a0fcab15dce63364b66e036cd2e7c771206a851c4e1fb4663147aa893020R1-R74) [[6]](diffhunk://#diff-cbc2681eed5eeac833e9ea171c33a79a91e0f9932da9a505ada26250ec63cc5dR15) [[7]](diffhunk://#diff-cbc2681eed5eeac833e9ea171c33a79a91e0f9932da9a505ada26250ec63cc5dR311-R318)

**Customer and Device Model Enhancements:**

* Extended the `Customer` model to include `id`, `country`, and `taxNumber` fields, and improved documentation for all fields. [[1]](diffhunk://#diff-55c4129390d69653f362dc95b2e2a17eff24ac9b58272d60d18b5c695e2be94cR3-R11) [[2]](diffhunk://#diff-55c4129390d69653f362dc95b2e2a17eff24ac9b58272d60d18b5c695e2be94cL19-R67)
* Enhanced the `CustomerDevice` model by adding fields for `fingerprint`, `ipv4`, `ipv6`, `client` (with a new enum `CustomerDeviceClient`), and `os`, and improved field descriptions. [[1]](diffhunk://#diff-e44780a0d33b99caa43c5cb5e9ec436606711795e512ad7c8fb3b6a52f2609aaR3-R10) [[2]](diffhunk://#diff-e44780a0d33b99caa43c5cb5e9ec436606711795e512ad7c8fb3b6a52f2609aaL18-R55) [[3]](diffhunk://#diff-06bc4d1ad40cb5488e312ba38f1ba24977fc2e3690ca976679cd5f5b42261450R1-R27)

**Common Types and Documentation Improvements:**

* Improved the `OsType` enum documentation and clarified its use across wallet payment methods and customer devices.
* Expanded the `PaymentMethodStatus` enum with additional statuses and detailed documentation for each value.

These changes collectively enable Cash App Pay support and improve the flexibility and clarity of customer and device data handling.

Release 8.6.0 (#684)

This release significantly improves the documentation and clarity of the Accounts API SDK by adding detailed JavaDoc comments to many classes, enums, and fields. It also introduces new document types and classes to support additional onboarding and verification requirements. The changes enhance maintainability and make the codebase much easier to understand for developers integrating with the API.

The most important changes are:

**Documentation and Clarity Improvements:**

* Added comprehensive JavaDoc comments to most classes, enums, and fields in the `com.checkout.accounts` package, explaining their purpose, usage, and field requirements. This includes details on required fields, expected formats, and API variant differences. [[1]](diffhunk://#diff-74497158e12fcc169150e9cb838360e0d7f4907cb87dc7c638e3225debab6abaR9-R28) [[2]](diffhunk://#diff-e569b01a51834986a530a27f4599a00b0154a93b93aab0822eb6ec55c7bee61eR8-R23) [[3]](diffhunk://#diff-83c15117d21da4a554aaa3fd5da12bca6e74e60cb04b8d6c5456374ff8402019R8-R28) [[4]](diffhunk://#diff-956e6921746c02cc98221a6ae4e687658fa92d6ed14f1fe928ae9e6e4cebaeccR8-R44) [[5]](diffhunk://#diff-cd189db098d9dfdcff000d70b99aea2576dd847a6af2b9763bfa6365bb72388bR8-R21) [[6]](diffhunk://#diff-ab2b1220c26ae5690dff45698d60441889c72f35223ff3c1450d6a62b13bafd4R9-R38) [[7]](diffhunk://#diff-d05774a973e569962c598dd6086335677bc56a1bb2d60a49215fdef384fd52dbR8-R32) [[8]](diffhunk://#diff-b3b13bc6911f1e4804cff95872a80ae1fafe551057fe88cd1e1c3c999a4e2bf8R8-R30) [[9]](diffhunk://#diff-c5fa468b797d67e48d234172a5ba814cb95404194b5aaa63a039a29805e8a5ebR8-R30) [[10]](diffhunk://#diff-7637f5e02efa6c1a9bc9a360aef0b6ccd5d6275c5c8768cc21e011db7ae4d457R8-R33)

**API Surface and Document Type Expansions:**

* Added new document types and enums to support additional onboarding requirements, such as `CertifiedAuthorisedSignatory`, `CertifiedAuthorisedSignatoryType`, and new values in `AccountsFilePurpose` (e.g., `ADDITIONAL_DOCUMENT`, `ARTICLES_OF_ASSOCIATION`, etc.). [[1]](diffhunk://#diff-d5414374879f2d11aa1900705576f809f1cefbac26b9459d4038130459f6e754R1-R34) [[2]](diffhunk://#diff-41b6ef21e7a8e7c0b288a8644c04c071634b0db1ee05d8269b7ac8bb97376f4aR1-R13) [[3]](diffhunk://#diff-3ef132d48a8ee6ad8f29ec72522c49cf4c6e2fa09ccd4c07d08b0666916ade69R5-R29)
* Enhanced enums with JavaDoc comments to clarify their purpose and usage, including distinctions between similar document types (e.g., `FinancialStatementsType` vs. `FinancialVerificationType`). [[1]](diffhunk://#diff-d4c25bd31f10b172cf87c35bffef9d7f87a3ebbde0eb517eb3f93410a5b2da06R5-R7) [[2]](diffhunk://#diff-05a366ae3a6812e50266d2ef62c932c3b731765378f3e2fe7d81309d75bda9ddR5-R7) [[3]](diffhunk://#diff-f21ae95d7efbc49cfc50391d196007531bd4ffaf0c0995da685922b9ee5b2443R5-R9) [[4]](diffhunk://#diff-0a92819c07b2c4e8799b6a13be5b77661fa1335d3887ff6d2456143403aadcf0R5-R8) [[5]](diffhunk://#diff-3c9b8d27ce3def38c67b11c9d9ee608f2d94f3e29c57f1a12c59325e553683c9R5-R8)

**API Method Documentation:**

* Added detailed JavaDoc comments to the `AccountsClient` interface methods (both async and sync), describing the purpose, parameters, and return values for file upload and retrieval operations. [[1]](diffhunk://#diff-cbcb5e828cfdb9bda58ecef6c6763e2ccd51ef014a518b8e88127eb1bc01087fR21-R49) [[2]](diffhunk://#diff-cbcb5e828cfdb9bda58ecef6c6763e2ccd51ef014a518b8e88127eb1bc01087fR127-R155)

**Field and Requirement Clarifications:**

* Clarified field requirements, formats, and validation rules (e.g., regex for file IDs, phone numbers, and national ID numbers) in class-level and field-level documentation. [[1]](diffhunk://#diff-6b949559fd055da9dbbcee8b08d1aae7a0e4b75ce76d36e98d92daddd64c3c7cL11-R12) [[2]](diffhunk://#diff-6b949559fd055da9dbbcee8b08d1aae7a0e4b75ce76d36e98d92daddd64c3c7cL23-R33) [[3]](diffhunk://#diff-83c15117d21da4a554aaa3fd5da12bca6e74e60cb04b8d6c5456374ff8402019R8-R28) [[4]](diffhunk://#diff-ab2b1220c26ae5690dff45698d60441889c72f35223ff3c1450d6a62b13bafd4R9-R38) [[5]](diffhunk://#diff-7637f5e02efa6c1a9bc9a360aef0b6ccd5d6275c5c8768cc21e011db7ae4d457R8-R33)

**Deprecation Notices:**

* Added deprecation notice to the `document` field in `Identification`, indicating it is not read by the API and will be removed in a future major version.

Release 8.5.0 (#679)

This release makes significant improvements to the handling of industry-specific payment data, especially for airline and accommodation information, and enhances documentation and type consistency throughout the SDK. The most important changes include refactoring the `Industry` entity to correctly map to API specifications, updating data models for airline and accommodation information, and improving code documentation and type safety.

### Industry Data Model Refactoring

* The `Industry` class now uses `IList<AirlineData>` and `IList<AccommodationData>` for `Airline` and `Accommodation` properties, respectively, replacing the previous singular object properties. This change ensures correct serialization/deserialization and proper mapping to the API's expected array structure.

### Airline and Accommodation Data Model Updates

* `AirlineData` and `AccommodationData` classes are updated with enhanced documentation, correct property types (e.g., `IList<Passenger>` for passengers), and improved handling of array/single-object deserialization. The `AccommodationData` class now uses `IList` for collections and string types for `State` and `Country` for better API compatibility. [[1]](diffhunk://#diff-7071d53d8d08e6f4c12dfc7e1720955826ea526d4291fc8b52d9db01ed4748daR2-R33) [[2]](diffhunk://#diff-11b5e4b3173127eeac6c071f480678bb74c41f2cd23fbc190e5e197cee67143bR9-R111)
* The `PaymentContextsAirlineData` and related context classes are updated for consistency, including the use of array types, improved documentation, and handling of string-based fields as specified by the API. [[1]](diffhunk://#diff-c9b3e4837a7a8967da70288770053b06f6c41854b834423c5d79ab451c902286R2-R31) [[2]](diffhunk://#diff-6d0b3d7fa8f23e3b9ac258c2c7be929214322c6eaeebd37c54da8ced4a41e7f4R6-R68) [[3]](diffhunk://#diff-6d49c2570f1bc096cff165e7023f2d3f95fc5302eb03a10f5ec4729615813324R6-R26) [[4]](diffhunk://#diff-815fe86c53250f03121e2b0876831a4bf5ffc9c78edbcbb70fe01ae10aee8df8L1-R35)

### Documentation and Specification Alignment

* Extensive XML documentation comments are added or improved across all affected models, clarifying the purpose, usage, and API mapping for each property. Remarks are included to highlight differences between the SDK and the API specification. [[1]](diffhunk://#diff-11b5e4b3173127eeac6c071f480678bb74c41f2cd23fbc190e5e197cee67143bR9-R111) [[2]](diffhunk://#diff-7071d53d8d08e6f4c12dfc7e1720955826ea526d4291fc8b52d9db01ed4748daR2-R33) [[3]](diffhunk://#diff-6d0b3d7fa8f23e3b9ac258c2c7be929214322c6eaeebd37c54da8ced4a41e7f4R6-R68) [[4]](diffhunk://#diff-6d49c2570f1bc096cff165e7023f2d3f95fc5302eb03a10f5ec4729615813324R6-R26) [[5]](diffhunk://#diff-815fe86c53250f03121e2b0876831a4bf5ffc9c78edbcbb70fe01ae10aee8df8L1-R35) [[6]](diffhunk://#diff-00704fcf5ccfe4391fd82dc0d0b651fe316ed75c4e3ce3b883e62c21a751e3ebR5-R90) [[7]](diffhunk://#diff-c9b3e4837a7a8967da70288770053b06f6c41854b834423c5d79ab451c902286R2-R31)

### Namespace and File Organization

* Several files are moved to more specific namespaces (`Requests`, `Responses`) for clarity and maintainability, and using directives are updated accordingly. [[1]](diffhunk://#diff-02d766a67d67f50f19850d15b33610d6e4984d0ad1777a4498826a6f701dab08L4-R4) [[2]](diffhunk://#diff-aa3b7dc435048c8de5097f1b7782886c6035ec27d1dbd9ed5272e447289b6f82L5-R5) [[3]](diffhunk://#diff-da72475f8e0913cf099f7c707ec6118e54c6a4ede4689e1db5e135df949a0f56L5-R5) [[4]](diffhunk://#diff-6b5cbe24e6a92abaf3d986fc7f78035e74cc010283f28499c48debe15e36336bL1-R3) [[5]](diffhunk://#diff-1c3ebb34636c994e74c1b85bbd374b08de434a1689643258dfedc330ccf275daL1-R3) [[6]](diffhunk://#diff-216732246d1e84b7198986c39dcfbd728e13b33c9f2f6001904470d708773d3fL1-R2) [[7]](diffhunk://#diff-216732246d1e84b7198986c39dcfbd728e13b33c9f2f6001904470d708773d3fR13)

### Type and Serialization Improvements

* List properties are consistently typed as `IList<T>` instead of `List<T>`, and custom JSON converters are used where the API may return either a single object or an array, ensuring robust (de)serialization. [[1]](diffhunk://#diff-7071d53d8d08e6f4c12dfc7e1720955826ea526d4291fc8b52d9db01ed4748daR2-R33) [[2]](diffhunk://#diff-c9b3e4837a7a8967da70288770053b06f6c41854b834423c5d79ab451c902286R2-R31) [[3]](diffhunk://#diff-11b5e4b3173127eeac6c071f480678bb74c41f2cd23fbc190e5e197cee67143bR9-R111)

These changes collectively improve the SDK’s alignment with the API, enhance type safety, and provide clearer documentation for developers.

Release 8.4.0 (#673)

Release 8.3.0 (#670)

- Add PaymentSetup accommodation/airline fields (totalNumberOfGuests, refundable, deliveryRecipient, host, totalNumberOfPassengers, travelType, tripType, ancillaries, insurance)
- Fix industry.airline and industry.accommodation serializing under the wrong keys on payment setups

Release 8.2.1 - Oauth scopes review (#668)

This release updates the `OAuthScope` enum to synchronize it with the latest Checkout.com API specification, ensuring all documented OAuth 2.0 scopes are present and correctly named. It adds missing scopes, removes deprecated ones, and improves test coverage to catch future discrepancies. Additionally, integration tests are updated to use the correct, current scopes.

**OAuthScope enum synchronization and improvements:**

* Added missing OAuth 2.0 scopes (e.g., `DISPUTES_SCHEME_FILES`, `FLOW_REFLOW`, `ISSUING_DISPUTES`, `VAULT_CUSTOMERS`, `VAULT_GPAYME_ENROLLMENT`, `VAULT_TOKENS_METADATA`, compliance-related scopes, etc.) and removed deprecated/retired ones (e.g., `MARKETPLACE`, `ISSUING_CARD_MGMT`, `ISSUING_CLIENT`, `FORWARD`, `FORWARD_SECRETS`) to match the API spec. [[1]](diffhunk://#diff-302daf625c19cc8a7a03bdbc42542bd819e74b329d3e2a71ee8d176d40f7456bR3-R33) [[2]](diffhunk://#diff-302daf625c19cc8a7a03bdbc42542bd819e74b329d3e2a71ee8d176d40f7456bR43-R70) [[3]](diffhunk://#diff-302daf625c19cc8a7a03bdbc42542bd819e74b329d3e2a71ee8d176d40f7456bR85-R96)
* Clarified the distinction between `PAYMENT_CONTEXT` and `GATEWAY_PAYMENT_CONTEXTS` scopes, correcting previous naming and value mismatches.
* Updated enum documentation to explain scope origins, naming, and special cases for easier maintenance.

**Test enhancements:**

* Added comprehensive tests to ensure all enum constants have non-blank, unique wire values, and that the enum is maintained in alphabetical order.
* Added tests to verify the presence and correct values of all newly added or renamed scopes, and to distinguish between similarly named but different scopes.

**Integration test updates:**

* Updated integration tests to use the correct, current scopes—removing retired ones and replacing them with their documented equivalents (e.g., using `ACCOUNTS` instead of `MARKETPLACE`, and the new issuing scopes instead of `ISSUING_CARD_MGMT`/`ISSUING_CLIENT`). [[1]](diffhunk://#diff-bac68bf5926ff0a0e5190d2306aec0494f21cfb2c00cbedbbea45ab9a324dd67L203-R205) [[2]](diffhunk://#diff-c3f2136dc5525f15662964e2bdfcc62b9545c6a634ad12cbbae466d6a2f1af4dL43-R47)

Release 8.2.0 (#665)

This release adds support for retrieving top-up instructions for currency accounts (sub-accounts) via the balances API, including both asynchronous and synchronous methods. It introduces new data models for top-up instructions and bank details, updates the OAuth scopes, and improves documentation across balances-related classes. Comprehensive unit tests for the new functionality are also included.

**New API Functionality:**

* Added asynchronous and synchronous methods to `BalancesClient` and `BalancesClientImpl` for retrieving top-up instructions (`retrieveTopUpInstructions` and `retrieveTopUpInstructionsSync`), including input validation and endpoint path construction. [[1]](diffhunk://#diff-4aaeddbce89b57608fdadc2c544b3b508517bcec9ffc2969ab86f7577f43b0e1R7-R52) [[2]](diffhunk://#diff-b18ae464e9998054429566b58566def3fa064f367b66b60676d2e49bf4c255b3R28-R58)
* Introduced new response and model classes: `TopUpInstructionsResponse`, `TopUpBankDetails`, and `TopUpFundingDetails` to represent top-up instructions and associated bank details. [[1]](diffhunk://#diff-5e469c62f4b3cda8acd06f37a6e3421296c3feea9891c28354d917101c4201b6R1-R42) [[2]](diffhunk://#diff-c5c594839a40e82c5be74edfd3d35feb2727778d331fb4544c23149589dc6f29R1-R26) [[3]](diffhunk://#diff-0df83cc85ce18d58c82d542885e277f37396364db2723de7b9d2966f89fdde42R1-R68)

**Authorization & Scopes:**

* Added the `BALANCES_TOP_UP_INSTRUCTIONS` OAuth scope to both the enum and test fixture setup to support the new endpoint. [[1]](diffhunk://#diff-302daf625c19cc8a7a03bdbc42542bd819e74b329d3e2a71ee8d176d40f7456bR8) [[2]](diffhunk://#diff-f012447d995546aa9e8bb0c0cbd5266663c8012dfc644a600881f47bf4ee182eR95)

**Documentation Improvements:**

* Enhanced Javadoc comments for `Balances`, `BalancesResponse`, and `CurrencyAccountBalance` to clarify the purpose and optionality of fields. [[1]](diffhunk://#diff-043b3ad097dd8d1c62eb7d9de2019372c49a333bfc993f63b12366a6a62ea8efR5-R43) [[2]](diffhunk://#diff-c03aa584ca201e8d06acd6e4d8228c62be41cf6e3b25fb92f4a054e3e3d5114fR9-R19) [[3]](diffhunk://#diff-f0d6dccd3b0f0f785507471f82746fe3afc5f0f54d5555e3f1a56c3ad586c6bdR8-R10) [[4]](diffhunk://#diff-f0d6dccd3b0f0f785507471f82746fe3afc5f0f54d5555e3f1a56c3ad586c6bdR21-R36)

**Testing:**

* Expanded `BalancesClientImplTest` to cover the new top-up instructions methods, including positive tests and parameterized negative tests for input validation. [[1]](diffhunk://#diff-b9e364eb4934ae41e615a300a1ddf45cc992b193ddd9dcf8bff18e539d743bbaR4) [[2]](diffhunk://#diff-b9e364eb4934ae41e615a300a1ddf45cc992b193ddd9dcf8bff18e539d743bbaR13-R14) [[3]](diffhunk://#diff-b9e364eb4934ae41e615a300a1ddf45cc992b193ddd9dcf8bff18e539d743bbaR24) [[4]](diffhunk://#diff-b9e364eb4934ae41e615a300a1ddf45cc992b193ddd9dcf8bff18e539d743bbaR34-R38) [[5]](diffhunk://#diff-b9e364eb4934ae41e615a300a1ddf45cc992b193ddd9dcf8bff18e539d743bbaR91-R130)

Release 8.1.0 (#662)

### Breaking changes (check at the end <img width="22" height="22" alt="image" src="https://github.com/user-attachments/assets/aff83459-ab22-4048-b196-8023ea41dc58" />)

This release introduces Bacs Direct Debit support to the SDK, enabling sending pre-notification (advance notice) events and full instrument lifecycle management for Bacs payment methods. The changes include new client interfaces and implementations, updates to serialization logic, and enhancements to the API surface. The most important changes are grouped below.

**Bacs Direct Debit Client and API Enhancements:**

- Added a new `BacsClient` interface and its implementation `BacsClientImpl` to support sending Bacs Direct Debit pre-notification events, with both asynchronous and synchronous methods. This client is configured to use secret key authorization only. [[1]](diffhunk://#diff-800ad7f65aaa8b74d6dd7d53dce4a96b721a5ba21acc5c1dee8666657e9e3d94R1-R29) [[2]](diffhunk://#diff-d864412750600caae657aa50096bec8ee7e2bdc4f876581f761e9f76d547e663R1-R39)
- Integrated the new `BacsClient` into the main API (`AbstractCheckoutApmApi` and `CheckoutApmApi`), making it accessible as `bacsClient()` alongside other APM clients. [[1]](diffhunk://#diff-548069506a2be2ee3efa7d6cc37ec53517d173aa51e3c934363f056c333b551aR3-R4) [[2]](diffhunk://#diff-548069506a2be2ee3efa7d6cc37ec53517d173aa51e3c934363f056c333b551aR19-R26) [[3]](diffhunk://#diff-548069506a2be2ee3efa7d6cc37ec53517d173aa51e3c934363f056c333b551aR35-R38) [[4]](diffhunk://#diff-dc0a5a29a25f41240cf2f7124d08a6ca7636863f346ae88cf39266273d0956d3R3-R24)

**Serialization and Instrument Support:**

- Updated the `GsonSerializer` to handle new Bacs-related classes, including request and response types for Bacs sources and instruments, ensuring correct (de)serialization of Bacs payment flows. This includes registering new instrument response subtypes for Bacs and updating the runtime type adapter factories to support polymorphic deserialization. [[1]](diffhunk://#diff-9b967a13c2a5016ea0995c3b77a5b750b221cf2d49970df6815d52970d5a73d8L115-R121) [[2]](diffhunk://#diff-9b967a13c2a5016ea0995c3b77a5b750b221cf2d49970df6815d52970d5a73d8L155-R162) [[3]](diffhunk://#diff-9b967a13c2a5016ea0995c3b77a5b750b221cf2d49970df6815d52970d5a73d8L170-R175) [[4]](diffhunk://#diff-9b967a13c2a5016ea0995c3b77a5b750b221cf2d49970df6815d52970d5a73d8L186-R231)

**Documentation:**

- Added comprehensive documentation to `README.md` demonstrating how to use the new Bacs Direct Debit features, including sending pre-notifications, creating, updating, and retrieving Bacs instruments, and taking payments using stored Bacs instruments.

### Breaking changes <img width="22" height="22" alt="image" src="https://github.com/user-attachments/assets/aff83459-ab22-4048-b196-8023ea41dc58" /><img width="22" height="22" alt="image" src="https://github.com/user-attachments/assets/aff83459-ab22-4048-b196-8023ea41dc58" /><img width="22" height="22" alt="image" src="https://github.com/user-attachments/assets/aff83459-ab22-4048-b196-8023ea41dc58" />

#### Property moved off a base class

GetInstrumentResponse.accountHolder removed from the base, now on each concrete variant. Forced by Gson: two fields mapping to the same JSON name throw at runtime, and the spec gives all five retrieve variants a different account-holder shape. Base-typed getAccountHolder() no longer compiles and needs a cast to the concrete variant.

#### Changed field types

instruments.create.InstrumentData.paymentType: payments.PaymentType → SepaPaymentType. The old enum serialized "Recurring"/"Regular"; StoreSepaInstrumentRequest pins lowercase recurring/regular, so SEPA store could not send a valid value. Callers passing PaymentType.RECURRING must switch enum — though no such call can currently succeed against the API.
GetSepaInstrumentResponse.instrumentData: InstrumentData → GetSepaInstrumentData, which adds the mandate type (Core/B2B) the old type omitted.

#### Wire value changed

UpdateInstrumentBankAccountRequest sent "type":"token", now sends "type":"bank_account". token is absent from the update discriminator mapping entirely, so PATCH /instruments/{id} could not be validated as a bank-account update. No test referenced the class before this PR.

#### Deserialization behaviour changed (throw → object)

type: "bacs" and type: "ach" on the create and get instrument responses previously threw JsonParseException, because the three RuntimeTypeAdapterFactory registrations have no default subtype. They now deserialize to the concrete type. Anyone catching that exception as control flow is affected. The factories remain strict for unmodelled types — deliberately, per decision A2.

#### Deprecated, not removed (non-breaking)
PaymentSourceType.SEPA — zero callers; use ID for the previous platform, SEPAV4 for the current one
CreateInstrumentResponse.customer — moves to the token and bank_account variants in the next major
Correction to something I told you earlier
previous.RequestSepaSource switching from PaymentSourceType.SEPA to PaymentSourceType.ID is wire-neutral, not a breaking change. Both constants already carried @SerializedName("id") on master, so the bytes are identical. I listed it as a wire change twice, including in the ledger — now fixed there too.

Release 8.0.0 (#660)

- The merchant-specific subdomain (environmentSubdomain) is now required. Set it, or call the deprecated useLegacyDomain() to keep using the shared checkout.com hosts.
- An invalid subdomain now throws instead of being silently ignored.
- Add optional amount to VoidRequest to support partial voids.
- Add the ISV (SaaS seller) payout schedule fields balanceMinimum, carryForwardEnabled and paymentInstrumentId.

Release 7.16.2 (#657)

This release fixes a defect in the payment sessions default values, refactors and clarifies the structure of payment session request classes, separating fields that are specific to session creation from those shared by all requests. It introduces a new base class, `PaymentSessionCreateBase`, to hold fields relevant only to session creation endpoints, and moves or removes several fields from other classes for better organization and alignment with API behavior. The changes also improve documentation and clarify which fields are required or optional in each context.

**Class hierarchy and structure refactoring:**

* Introduced a new abstract base class, `PaymentSessionCreateBase`, which contains fields that are only accepted when creating a payment session (e.g., `capture`, `paymentType`, `locale`, `authorizationType`, `description`, `displayName`, `paymentPlan`, `risk`). This class is now the parent for both `PaymentSessionCreateRequest` and `PaymentSessionCompleteRequest`, ensuring these fields are only present where appropriate.
* Updated `PaymentSessionInfo` to remove fields that are now in `PaymentSessionCreateBase`, and clarified its role as holding only fields shared by all payment session requests. Improved class-level documentation to reflect this separation. [[1]](diffhunk://#diff-0fe60fb620a42c06b6064c12ab6cd10f92e5516a58d63288966dd90b4e78fccbL28-R28) [[2]](diffhunk://#diff-0fe60fb620a42c06b6064c12ab6cd10f92e5516a58d63288966dd90b4e78fccbL72-L77) [[3]](diffhunk://#diff-0fe60fb620a42c06b6064c12ab6cd10f92e5516a58d63288966dd90b4e78fccbR112-L132) [[4]](diffhunk://#diff-0fe60fb620a42c06b6064c12ab6cd10f92e5516a58d63288966dd90b4e78fccbL145-L172)

**Request class adjustments:**

* Changed `PaymentSessionCreateRequest` and `PaymentSessionCompleteRequest` to extend the new `PaymentSessionCreateBase` instead of `PaymentSessionInfo`, and removed duplicated fields now inherited from the new base class. [[1]](diffhunk://#diff-61ad0790471bea4c725dff7d4b0de0689a14e39b3392dc1a78c7726ac98bf1c6L25-R23) [[2]](diffhunk://#diff-ab9930e4f1af6784ab8b2cfd54239645847ac508ecbf7f5b24e32a9959f0fa10L19-R23)
* Updated `PaymentSessionSubmitRequest` to allow optional overriding of `capture` and `paymentType`, with clear documentation that leaving these fields unset preserves the values from session creation (or defaults). Also clarified that only `sessionData` is required. [[1]](diffhunk://#diff-462798be46d92649c7cbfaa6437a1d0ed387622126e158f4595f4294dbe13ed6R16-R19) [[2]](diffhunk://#diff-462798be46d92649c7cbfaa6437a1d0ed387622126e158f4595f4294dbe13ed6L27-R52)

**Documentation and code cleanup:**

* Improved and clarified Javadoc comments throughout the affected classes, specifying field requirements, default behaviors, and the intended use of each class. [[1]](diffhunk://#diff-d6f5d99bd176e3903e7ee1341a57935dfcf6fca892a9b19525d02442336b09b7R1-R89) [[2]](diffhunk://#diff-0fe60fb620a42c06b6064c12ab6cd10f92e5516a58d63288966dd90b4e78fccbL28-R28) [[3]](diffhunk://#diff-462798be46d92649c7cbfaa6437a1d0ed387622126e158f4595f4294dbe13ed6R16-R19)
* Removed unused imports and redundant annotations from affected files for code clarity. [[1]](diffhunk://#diff-78db8b59f0dbc7931b0e84c4d2093728a855b4ed9f7bb363625d260753c0ddb7L4-L9) [[2]](diffhunk://#diff-ab9930e4f1af6784ab8b2cfd54239645847ac508ecbf7f5b24e32a9959f0fa10L3-L5) [[3]](diffhunk://#diff-61ad0790471bea4c725dff7d4b0de0689a14e39b3392dc1a78c7726ac98bf1c6L6-L8) [[4]](diffhunk://#diff-0fe60fb620a42c06b6064c12ab6cd10f92e5516a58d63288966dd90b4e78fccbL5-L17)

**Test updates:**

* Updated a test in `FlowLocaleAndStatusDeserializationTest` to reflect the refactored request structure, ensuring correct serialization after the changes.