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] [2] [3] [4] [5] [6] [7]

Customer and Device Model Enhancements:

• Extended the Customer model to include id, country, and taxNumber fields, and improved documentation for all fields. [1] [2]
• Enhanced the CustomerDevice model by adding fields for fingerprint, ipv4, ipv6, client (with a new enum CustomerDeviceClient), and os, and improved field descriptions. [1] [2] [3]

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] [2] [3] [4] [5] [6] [7] [8] [9] [10]

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] [2] [3]
• Enhanced enums with JavaDoc comments to clarify their purpose and usage, including distinctions between similar document types (e.g., FinancialStatementsType vs. FinancialVerificationType). [1] [2] [3] [4] [5]

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] [2]

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] [2] [3] [4] [5]

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] [2]
• 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] [2] [3] [4]

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] [2] [3] [4] [5] [6] [7]

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] [2] [3] [4] [5] [6] [7]

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] [2] [3]

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)

⚠️ Breaking changes (see at the bottom)

This release adds support for retrieving paginated address document verification attempts and their associated assets (such as document images), and introduces several new response models to represent these assets. It also enhances the ApiClient interface to allow custom headers for PATCH requests. Additionally, it improves type safety for address country codes and updates the report response model.

Address Document Verification API enhancements:

• Added methods to AddressDocumentVerificationClient and its implementation to retrieve paginated verification attempts (with optional query filters) and to fetch assets (document images) uploaded for a specific attempt, both asynchronously and synchronously. [1] [2] [3] [4] [5] [6] [7] [8]
• Introduced new response models: AddressDocumentVerificationAttemptAsset, AddressDocumentVerificationAttemptAssetType, and AddressDocumentVerificationAttemptAssetsResponse to represent and paginate assets. [1] [2] [3]

ApiClient interface improvements:

• Added overloaded patch and patchAsync methods to ApiClient and its implementation, allowing custom headers to be passed with PATCH requests. [1] [2] [3] [4]

Type safety and model updates:

• Changed the country field in the Address response model from String to the CountryCode enum for better type safety. [1] [2]
• Renamed the signedUrl field to pdfReport in AddressDocumentVerificationReportResponse and improved its documentation.…on_date

⚠️ Breaking changes

Note: the PhysicalCardRequest and VirtualCardRequest constructors keep their arity and parameter types, so positional constructor calls still compile. Only the parameter name changed.

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] [2] [3]
• 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] [2]

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] [2]
• Introduced new response and model classes: TopUpInstructionsResponse, TopUpBankDetails, and TopUpFundingDetails to represent top-up instructions and associated bank details. [1] [2] [3]

Authorization & Scopes:

• Added the BALANCES_TOP_UP_INSTRUCTIONS OAuth scope to both the enum and test fixture setup to support the new endpoint. [1] [2]

Documentation Improvements:

• Enhanced Javadoc comments for Balances, BalancesResponse, and CurrencyAccountBalance to clarify the purpose and optionality of fields. [1] [2] [3] [4]

Testing:

• Expanded BalancesClientImplTest to cover the new top-up instructions methods, including positive tests and parameterized negative tests for input validation. [1] [2] [3] [4] [5]

Release 8.1.0 (#662)

Breaking changes (check at the end )

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] [2]
• Integrated the new BacsClient into the main API (AbstractCheckoutApmApi and CheckoutApmApi), making it accessible as bacsClient() alongside other APM clients. [1] [2] [3] [4]

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] [2] [3] [4]

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

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] [2] [3] [4]

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] [2]
• 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] [2]

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] [2] [3]
• Removed unused imports and redundant annotations from affected files for code clarity. [1] [2] [3] [4]

Test updates:

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